core/docs/CHANGES-0.18.0-phase1.md

v0.18.0 Phase 1 — Changes Guide

New Files (drop in place)

File	Description
server/database/migrations/004_v0180_memories.sql	Postgres migration — memories table, indexes, trigger
server/database/migrations/sqlite/003_v0180_memories.sql	SQLite equivalent
server/models/models_memory.go	Memory + MemoryFilter model structs + scope/status constants
server/store/store_memory.go	MemoryStore interface definition
server/store/postgres/memory.go	Postgres MemoryStore implementation
server/store/sqlite/memory.go	SQLite MemoryStore implementation
server/tools/memory.go	memory_save + memory_recall tools with late registration
server/handlers/memory_inject.go	BuildMemoryHint() for context injection
docs/DESIGN-0.18.0.md	Design document

Existing File Modifications

1. server/store/interfaces.go

Add to the Stores struct (after ResourceGrants):

Memories       MemoryStore

The MemoryStore interface itself is in the new store_memory.go file (same package, separate file for cleanliness).

2. server/store/postgres/stores.go

Add to the NewStores() return:

Memories:       NewMemoryStore(),

3. server/store/sqlite/stores.go

Add to the NewStores() return:

Memories:       NewMemoryStore(),

4. server/main.go

Add after the existing tool registrations (~line 169):

// Memory tools (v0.18.0) — late registration, needs stores
tools.RegisterMemoryTools(stores)

5. server/handlers/completion.go

In loadConversation(), add memory injection after the KB hint block (~line 798, after the BuildKBHint block):

// ── Memory injection (recall known facts about user) ──
if memHint := BuildMemoryHint(context.Background(), h.stores, userID, personaID); memHint != "" {
    messages = append(messages, providers.Message{
        Role:    "system",
        Content: memHint,
    })
}

6. VERSION

0.18.0

7. docs/ROADMAP.md

Mark Phase 1 items as complete (Data Model, Tools, Memory Injection basics).

---

Testing Checklist

1. Migration runs clean — both Postgres and SQLite
2. Tools register — check startup logs for 🔧 Registered tool: memory_save and memory_recall
3. memory_save — in a chat, tell the AI something personal ("I prefer Go over Python"). The AI should call memory_save.
4. memory_recall — in a NEW chat, ask "what programming language do I prefer?" The AI should call memory_recall and find it.
5. Persona scoping — with a Persona active, memories save as persona_user scope. Without a Persona, they save as user scope.
6. Upsert — saving the same key twice updates the value instead of creating a duplicate.
7. Injection — memories appear in the system prompt context (check server logs for 🧠 Injected N memories).

Architecture Notes

• Memory injection happens in loadConversation() as a system message, same pattern as KB hints and compaction summaries
• Scope priority in Recall: persona_user > persona > user (most specific wins)
• The unique index on (scope, owner_id, COALESCE(user_id, nil_uuid), key) prevents duplicate keys within a scope
• Confidence is LLM-provided: 1.0 for explicit statements, lower for inferences
• Status field supports Phase 2's review pipeline (pending_review, archived)
• Embedding column exists but is unused in Phase 1 — Phase 2 adds semantic recall