EPIC: v0.9.0 Phase 3 — graduate memory from flat markdown to a typed, graph-structured store

[Hmbown]

Thesis

Phase 1/2 (#489) borrowed Claude Code's memory integration shape — hierarchy, /memory, @import, quick-add. The substrate is still flat markdown (~/.deepseek/memory.md + anchors.md + JSONL cycle archive). Phase 3 graduates the substrate: typed memory classes, salience-weighted recall, graph edges between related memories, first-class contradiction tracking, and a hygiene loop that keeps the store from becoming stagnant.

Built natively in Rust under crates/tui/src/memory/. No new runtime dependencies. SQLite (already in the workspace via rusqlite in deepseek-state) with FTS5 for the substrate; vectors deferred until proven necessary.

Why now

Phase 1/2 needs to settle in production first. Users need to be living with /memory and @import before we know what the typed model should actually carve at, and what the auto-extraction signal looks like in the wild. This EPIC is soft-blocked on #491, #492, #493, #494, #495, #496, #497 shipping and getting at least one release of soak time.

Why not an external dependency

Considered wiring an external memory service (own MCP server). Rejected: adds a Node runtime requirement, splits the storage story across two systems, and the sophisticated parts of those designs (typed records, multi-signal recall, graph topology, contradiction tracking) are concepts we can implement natively in Rust without taking on a runtime dependency.

Why SQLite + FTS5

• OLTP shape matches the access pattern (frequent small reads/writes, point lookups by id, status updates).
• FTS5 ships built into SQLite — text search without a separate index.
• Recursive CTEs cover graph traversal until proven insufficient.
• sqlite-vec exists if/when vector recall becomes necessary.
• Single-file backup, debuggable from any machine with sqlite3.

DuckDB rejected: analytical/OLAP shape, wrong fit for frequent small writes. LanceDB rejected for now: vector-first, columnar, versioning-on-every-write would create write amplification on status updates; revisit specifically if embedding-based recall becomes core. SurrealDB rejected: too young, recursive CTEs cover the graph case.

Sub-issues (all v0.9.0)

• MEMORY: substrate — MemoryBackend trait + SQLite-backed store (FTS5) #535 MEMORY: substrate — MemoryBackend trait + SQLite-backed store (FTS5)
• MEMORY: engine — typed memory model + multi-signal recall #536 MEMORY: engine — typed memory model + multi-signal recall
• MEMORY: topology — graph edges + contradiction detection #537 MEMORY: topology — graph edges + contradiction detection
• MEMORY: loop — lifecycle hooks + background auto-extraction #538 MEMORY: loop — lifecycle hooks + background auto-extraction
• MEMORY: hygiene — decay scoring, periodic review subagent, one-key drop #539 MEMORY: hygiene — decay scoring, periodic review subagent, one-key drop

Out of scope

• Replacing session_manager.rs / runtime_threads.rs / task_manager.rs — those persist execution state, not memory. They keep their own SQLite stores.
• Vector embeddings (deferred; revisit only if FTS5 + signals proves insufficient).
• Multimodal memory blobs.
• Team / shared memory across users.

Acceptance signals

• User-facing surface (/memory editor, # add, @import) unchanged from Phase 1/2.
• Existing ~/.deepseek/memory.md and anchors.md migrate cleanly on first run; originals preserved as .bak.
• Recall is typed and ranked, not BM25-over-flat-files.
• Contradictions surfaced to the user, never silently auto-resolved.
• Memory store gets less annoying over time, not more — measured by user-initiated drops trending down.

[merchloubna70-dot]

Suggestion: close most of this EPIC via mem0 MCP instead of building from scratch

Before investing in a custom SQLite schema + typed memory engine + graph topology layer, it's worth considering mem0 (Apache 2.0, 53k ⭐) as the substrate — plugged in through DeepSeek-TUI's existing MCP client with zero Rust code.

What mem0 covers out of the box

Requirement	mem0 OSS	Notes
Structured memory store	✅	Vector (Qdrant) + KV + optional graph
Contradiction detection	✅	LLM-driven: auto-DELETE conflicting memories on ingest
Graph edges (causes / supersedes / contradicts)	✅	Requires Neo4j sidecar
Typed memory classes (semantic/episodic/etc.)	❌	Pro only; OSS is untyped
Salience / decay scoring	❌	Pro only
MCP tool surface	✅	add_memory, search_memories, update_memory, delete_memory, list_entities, search_graph…

Proposed mcp.json (fully local, no cloud API key)

{
  "mcpServers": {
    "mem0": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/elvismdev/mem0-mcp-selfhosted.git",
        "mem0-mcp-selfhosted"
      ],
      "env": {
        "MEM0_PROVIDER": "ollama",
        "MEM0_LLM_MODEL": "deepseek-v4-flash",
        "MEM0_EMBEDDING_MODEL": "bge-m3",
        "MEM0_USER_ID": "deepseek-tui-user"
      }
    }
  }
}

Prerequisites: Qdrant running on localhost:6333, Ollama on localhost:11434. Both are single-binary, no Docker required.

What this closes

• MEMORY: substrate — MemoryBackend trait + SQLite-backed store (FTS5) #535 (MemoryBackend trait + SQLite store) → mem0 is the backend; no custom SQLite schema needed
• MEMORY: engine — typed memory model + multi-signal recall #536 (typed engine + multi-signal recall) → partially covered (semantic search + LLM recall); typed classes are a thin wrapper you could add later
• MEMORY: topology — graph edges + contradiction detection #537 (graph edges + contradiction detection) → covered via Neo4j sidecar + mem0's built-in contradiction logic

Known risks

• The official mem0 MCP package is archived (cloud-only); the local path relies on a community fork (elvismdev/mem0-mcp-selfhosted) — worth forking and pinning a version
• CVSS 8.1 injection vuln disclosed 2026-04-17 affects PGVector/Neptune backends; Qdrant backend is not affected
• Salience/decay and typed memory classes remain OSS gaps — if those matter, a thin Rust wrapper (~200 lines) on top of mem0's REST API is far less work than the full custom stack

This approach would reduce the implementation work by roughly 70% and let the mem0 community maintain the hard parts (vector search, graph traversal, contradiction logic) while DeepSeek-TUI stays focused on Rust.

Happy to send a PR wiring up the MCP config and documenting the self-hosted setup if this direction looks viable.

---

wangfengcsu@qq.com

[GoDiao]

Hi! I'm really interested in the memory system direction outlined here and would love to contribute to the Phase 3 effort.

I've contributed to a similar memory + session system in MiniCode — a lightweight Claude Code clone in TypeScript. My work covers:

• Hierarchical context discovery: global → project → rules, with recursive @include resolution and cycle detection (src/memory.ts)
• Session persistence: JSONL event stream with UUID chain, compact boundaries, fork/rename/cleanup (src/session.ts)
• Budget-aware loading: per-file and total char caps with truncation markers
• Content dedup: SHA256-based dedup so overlapping instruction files don't waste context

I know the jump from TS flat-file to Rust + SQLite + typed memory model is significant, and I don't want to just show up with a big PR that doesn't align with your vision. A few questions before I start coding:

1. Are you open to external contributions on MEMORY: substrate — MemoryBackend trait + SQLite-backed store (FTS5) #535 (substrate) at this point, or do you want to lay the foundation yourself first?
2. For the MemoryBackend trait — are you envisioning a single trait with remember / recall / forget, or a more granular split (read/write/search as separate traits)?
3. Any preference on the SQLite schema approach? I was thinking a single memories table with a JSON metadata column + FTS5 virtual table for full-text search, but happy to go with whatever fits your roadmap.

Happy to start smaller if there's a foundational piece you'd like outsourced. Thanks for the great project!

[merchloubna70-dot]

@GoDiao Great background — the MiniCode session persistence and @include cycle detection work is directly relevant here.

We've already submitted a proposal and some groundwork from a different angle: instead of building the SQLite substrate from scratch, we suggested wiring mem0 (Apache 2.0, 53k ⭐) as the memory backend via DeepSeek-TUI's existing MCP client — zero new Rust infrastructure needed for the storage layer. The full proposal with a ready-to-use mcp.json config is in our earlier comment above.

That said, your questions about the MemoryBackend trait design are exactly the right ones to ask, and a native Rust path may still be preferable for offline/air-gapped use cases where running Qdrant + Ollama isn't practical.

On your specific questions:

1. External contributions on MEMORY: substrate — MemoryBackend trait + SQLite-backed store (FTS5) #535: Hunter hasn't signaled either way yet (75 open PRs pending), but the issue is tagged v0.9.0 and marked as "soft-blocked on Phase 1/2 settling in production first." Starting with a small, focused PR on the trait definition alone (not the full SQLite impl) is probably the lowest-friction entry point.

2. MemoryBackend trait shape: A single trait with remember / recall / forget / search makes the most sense for the initial cut — mirrors how the existing recall_archive.rs BM25 tool already exposes its surface. Splitting read/write/search into separate traits is better deferred until there are multiple backend impls to drive the abstraction.

3. SQLite schema: Your instinct (single memories table + JSON metadata + FTS5 virtual table) matches exactly what MEMORY: substrate — MemoryBackend trait + SQLite-backed store (FTS5) #535 sketches. One addition worth considering: a salience float column updated on each recall hit, so the hygiene loop (MEMORY: hygiene — decay scoring, periodic review subagent, one-key drop #539) has something to sort by without a separate table.

If you want to coordinate, we're tracking everything under the feat/ branches on https://github.com/merchloubna70-dot/DeepSeek-TUI — feel free to look at what's already been stubbed out.

---

wangfengcsu@qq.com

[GoDiao]

@merchloubna70-dot dude 你是哪个agent