Memory

CRUD operations for facts, profile entries, patterns, learning proposals, and memory health.

Mental model

• Facts are source-of-truth memory records.
• Profile entries are curated always-visible memory with direct provenance.
• Patterns are derived memory over supporting facts. The API still uses the historical /observations route name.
• Learning candidates are reviewable continual-learning proposals.

Facts

List facts

curl "http://localhost:6877/facts?limit=20&offset=0" \
  -H "Authorization: Bearer $API_KEY"

Get fact

curl http://localhost:6877/facts/42 \
  -H "Authorization: Bearer $API_KEY"

Returns the fact with its entities and linked facts.

Update fact

curl -X PATCH http://localhost:6877/facts/42 \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text": "Updated fact text"}'

Delete fact

curl -X DELETE http://localhost:6877/facts/42 \
  -H "Authorization: Bearer $API_KEY"

Profile Entries

Profile entries are curated always-visible memory. They are separate from raw facts and keep direct provenance through source fact or observation ids.

List profile entries

curl http://localhost:6877/memory/profile \
  -H "Authorization: Bearer $API_KEY"

Create profile entry

curl -X POST http://localhost:6877/memory/profile \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"kind":"preference","summary":"User prefers direct engineering feedback.","source_fact_ids":[42]}'

Get profile entry

curl http://localhost:6877/memory/profile/7 \
  -H "Authorization: Bearer $API_KEY"

Returns the entry with its source facts and source patterns.

Update profile entry

curl -X PATCH http://localhost:6877/memory/profile/7 \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"summary":"User prefers concise, direct engineering feedback."}'

Archive profile entry

curl -X DELETE http://localhost:6877/memory/profile/7 \
  -H "Authorization: Bearer $API_KEY"

Patterns

Patterns are stored behind the historical observations API names.

List patterns

curl http://localhost:6877/observations \
  -H "Authorization: Bearer $API_KEY"

Get pattern

curl http://localhost:6877/observations/7 \
  -H "Authorization: Bearer $API_KEY"

Returns the pattern with its supporting facts.

Update pattern

curl -X PATCH http://localhost:6877/observations/7 \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"summary": "Updated observation"}'

Delete pattern

curl -X DELETE http://localhost:6877/observations/7 \
  -H "Authorization: Bearer $API_KEY"

Learning candidates

Create reviewable continual-learning candidates from recent memory feedback and runtime evidence:

curl -X POST http://localhost:6877/memory/learning/propose \
  -H "Authorization: Bearer $API_KEY"

List candidates:

curl http://localhost:6877/memory/learning/candidates \
  -H "Authorization: Bearer $API_KEY"

Update a candidate status:

curl -X PATCH http://localhost:6877/memory/learning/candidates/12/status \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"status":"approved"}'

Stats

curl http://localhost:6877/stats \
  -H "Authorization: Bearer $API_KEY"

{
  "fact_count": 245,
  "observation_count": 38,
  "dream_count": 5
}

Audit and cleanup

Inspect memory health:

curl http://localhost:6877/memory/audit \
  -H "Authorization: Bearer $API_KEY"

Preview cleanup before applying it:

curl -X POST http://localhost:6877/memory/prune/dry-run \
  -H "Authorization: Bearer $API_KEY"

Apply cleanup after reviewing the dry run:

curl -X POST http://localhost:6877/memory/prune/apply \
  -H "Authorization: Bearer $API_KEY"

Inspect what memory would be retrieved for a query:

curl -X POST http://localhost:6877/memory/recall/inspect \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query":"what should the agent know about my backend architecture preferences?"}'

Purge

Delete all memory data:

curl -X POST http://localhost:6877/memory/clear \
  -H "Authorization: Bearer $API_KEY"

Clear only patterns (keep facts):

curl -X POST http://localhost:6877/memory/observations/clear \
  -H "Authorization: Bearer $API_KEY"