Vault write-back: persist memories as markdown files

[raphasouthall]

Summary

NeuroStack currently reads the vault and builds an index, but never writes back. Memories (vault_remember) are stored only in SQLite. If the DB is lost, memories are gone. This issue proposes opt-in vault write-back so memories are persisted as markdown files alongside user notes.

Motivation

• Memories don't survive DB wipes or corruption
• Not visible in Obsidian - users can't browse or link to them
• No git history for memories
• Competitors (mem0, Zep, Letta) store memories in opaque databases - NeuroStack writing to user-owned markdown is a differentiator
• For users with empty/small vaults, write-back lets NeuroStack build the vault alongside the user

Design (5-agent stochastic consensus)

Quarantined directory

All writes go to a single configurable directory (default: {vault_root}/.neurostack/). NeuroStack NEVER writes outside this folder. User notes are sacred.

.neurostack/
  memories/
    decision/
      2026-03/
        mem-25.md
    learning/
      2026-03/
        mem-29.md
  summaries/
    work-nyk-europe-azure.md

What gets written

Written to files	Stays DB-only
Persistent memories (no TTL) of type: decision, convention, learning, bug	Memories with expires_at set (ephemeral)
Project summaries (one per workspace)	Observations, context (opt-in via config)
	Embeddings, triples, communities (derived data)

File format

---
memory_id: 25
entity_type: decision
tags: [neurostack, reddit, launch-strategy-v2]
source_agent: claude-code
workspace: null
created_at: 2026-03-16T09:08:00Z
updated_at: null
revision_count: 1
---

Reddit launch strategy v2 (revised 2026-03-16): Phase 1 go dark until March 30...

CRUD mapping

Operation	DB	File
vault_remember	INSERT	Write file (if persistent, qualifying type)
vault_update_memory	UPDATE	Overwrite file, bump updated_at
vault_forget	DELETE	Delete file
vault_merge	DELETE source, INSERT merged	Delete source files, write merged file
TTL expiry	DELETE	No file exists, nothing to clean

Source of truth

DB remains authoritative. Files are readable exports. If they diverge, neurostack sync reconciles from DB.

Watcher exclusion

.neurostack/ is hardcoded-excluded from the watcher to prevent index-writes-trigger-reindex loops.

Git

.neurostack/ starts gitignored. User can opt in to git tracking. Never auto-commit.

Config

[writeback]
enabled = false  # opt-in
path = ".neurostack"  # relative to vault_root
include_observations = false  # opt-in for noisy types

Migration

• neurostack migrate write-back --dry-run - preview what would be written
• neurostack migrate write-back - write files for all qualifying existing memories
• neurostack sync - reconcile files vs DB (DB wins on conflict)

What NOT to build

• No bidirectional sync (file edits flowing back to DB)
• No wiki-links from memory files into user notes
• No auto-commit
• No writing outside .neurostack/
• No triples/communities as files (derived data stays in DB)
• No changes to the existing insight-harvest 3-tier system

Future phases (out of scope for MVP)

• Phase 2: Project summaries auto-generated per workspace
• Phase 3: Annotate user notes with backlinks (opt-in, append-only)
• Phase 4: neurostack sync --file-first for users who edit memory files in Obsidian