Memory and knowledge graph reference

Bestie starts with local SQLite memory. Memory is not perfect recall; it is governed local context that the owner can inspect, pause, approve, edit, forget, export, and clean up.

The knowledge graph extends memory with entities and relations so durable project facts, decisions, people, tools, and workflows can be connected instead of stored as loose text confetti.

Memory policy

The model may propose durable memories through internal tools and post-turn reasoning. Runtime config controls what happens next:

Policy	Behavior
allow	Store allowed non-secret candidates directly.
ask	Queue allowed non-secret candidates for owner approval.
deny	Reject memory writes.

Eligible memory types include:

• communication preferences
• explicit preferences
• non-sensitive user facts
• project context
• durable decisions

Sensitive personal details, family/relationship context, health context, financial details, and private identifiers should go to pending approval.

Never store passwords, tokens, payment details, API keys, OAuth authorization values, recovery phrases, or one-off venting unless the user explicitly asks and the content is safe to keep.

Retrieval policy

memory.retrievalPolicy controls how approved memories are organized before prompt injection:

Policy	Behavior
full	Injects active memories broadly in the existing ordering.
governed	Still uses active memories, but labels or prioritizes records by governance metadata such as pinning, confidence, expiry, scope, and supersession.

Use governed retrieval when memory quality matters more than dumping every remembered sentence into context like a raccoon emptying a drawer.

bestie memory governance status
bestie memory governance policy full
bestie memory governance policy governed

Current storage

The SQLite store tracks:

• active memories
• pending memories
• persisted terminal, Telegram, Zalo, cron, and UI messages when enabled
• pause/resume state
• pending action approvals
• memory governance metadata
• hygiene snapshots
• knowledge graph entities, relations, pending items, and audit events

Doctor verifies that the memory database can be created, opened, and migrated.

Memory lifecycle metadata

Each approved memory can carry metadata for recall and cleanup:

Field	Purpose
scope	core, project, or session context.
pinned	Prevents accidental cleanup or deprioritization.
confidence	Indicates how certain the memory is.
expires_at	Allows temporary context to expire.
superseded_by	Points to a newer memory that replaced this one.
last_accessed_at	Tracks retrieval usage.
access_count	Helps identify frequently used context.

Pinned core memories should be rare. If every memory is core, none of them are core. That’s not strategy, that’s hoarding with JSON.

User controls

bestie memory status
bestie memory pause
bestie memory resume
bestie memory list
bestie memory list --scope core
bestie memory tiers
bestie memory summary
bestie memory search concise
bestie memory add communication_preference "User prefers concise replies."
bestie memory inspect 1
bestie memory edit 1 "Updated memory text."
bestie memory pin 1
bestie memory unpin 1
bestie memory move 1 --scope project
bestie memory supersede 1 2
bestie memory forget 1
bestie memory export
bestie memory clear --yes

Terminal and owner channels also support memory commands such as /memory, /memory pause, /memory resume, and /pending.

Persisted messages

Inspect recent persisted messages:

bestie memory messages --limit 20
bestie memory messages --limit 20 --role user
bestie memory messages --limit 20 --role assistant
bestie memory messages --limit 20 --role system

Search persisted messages:

bestie memory messages search project --limit 10
bestie memory messages search project --limit 10 --role user

Treat message exports and search output as private. They can contain sensitive conversation context even when secret-like values are supposed to be blocked from durable memory.

Pending memories

List and search pending memories:

bestie memory pending --limit 20
bestie memory pending search hanoi --limit 10

Inspect, approve, or reject one pending memory:

bestie memory pending inspect 3
bestie memory approve 3
bestie memory reject 3

Reject the whole pending queue only after review:

bestie memory reject-all --yes

If memory is paused, Bestie should not approve pending memories until memory is resumed.

Analyze and clean memory

Analyze duplicate, stale, or conflicting memories:

bestie memory analyze
bestie memory analyze --mode duplicates
bestie memory analyze --mode stale
bestie memory analyze --mode conflicts
bestie memory analyze --json

Preview cleanup:

bestie memory cleanup --dry-run
bestie memory cleanup --dry-run --json
bestie memory hygiene status
bestie memory hygiene doctor
bestie memory hygiene trend
bestie memory rebalance --dry-run

Apply cleanup only after reviewing the plan:

bestie memory cleanup --apply --yes
bestie memory cleanup --apply --yes --json
bestie memory hygiene --apply --yes
bestie memory hygiene doctor --fix
bestie memory rebalance --apply --yes

Cleanup should consolidate before deleting. Conflicts should be reviewed manually instead of being auto-deleted.

Maintenance reports

Memory maintenance reports are cron-backed checks. They report hygiene trends, duplicate groups, stale memories, conflicts, and safe next commands without mutating memory by default.

Install the default weekly report:

bestie memory maintenance install --channel telegram:123456789

Use Zalo instead:

bestie memory maintenance install --channel zalo:123456789

Check or remove the schedule:

bestie memory maintenance status
bestie memory maintenance remove
bestie memory digest

Knowledge graph scope

The graph stores durable entities and relationships derived from approved memory/tool writes and bounded reasoning passes.

Common entity kinds include:

• person
• project
• preference
• tool
• skill
• topic
• organization
• location
• decision
• concept

Relations connect entities with evidence, confidence, sensitivity, scope, and status metadata.

Knowledge graph commands

bestie memory graph status
bestie memory graph search Bestie
bestie memory graph entities --kind project
bestie memory graph relations --limit 20
bestie memory graph inspect entity 1
bestie memory graph inspect relation 1
bestie memory graph add entity project Bestie
bestie memory graph add relation 1 works_on 2 "Owner is building Bestie."
bestie memory graph analyze --json
bestie memory graph hygiene --json
bestie memory graph review --limit 5
bestie memory graph export

Pending graph writes

Graph writes follow memory.writePolicy. When policy is ask, graph candidates are queued for owner review.

bestie memory graph pending --limit 10
bestie memory graph pending inspect 1
bestie memory graph pending sanitize 1
bestie memory graph approve 1
bestie memory graph reject 1
bestie memory graph reject-all --yes

Sanitization redacts secret-like values from pending graph payloads when possible.

Graph hygiene and cleanup

Graph hygiene can report duplicate entity candidates, conflicting relations, orphan entities, low-confidence relations, and pending items.

Review before mutating:

bestie memory graph review --limit 5

Apply targeted cleanup only after inspection:

bestie memory graph merge entity 1 2 --yes
bestie memory graph update relation 1 --confidence 0.8 --evidence "Verified evidence" --yes
bestie memory graph forget relation 1 --yes

Graph cleanup follows memory.deletePolicy and should leave audit events. Do not bulk-delete graph facts just because a hygiene report looks messy.

Export and clear

Export memory data as JSON:

bestie memory export
bestie memory graph export

Exports are private data. Store and share them carefully.

Clear memory only when you intentionally want to remove local memory data:

bestie memory clear --yes

clear requires --yes. Without it, Bestie refuses to delete memory data.