cognitive-vault 0.1.0

Local-first AI memory layer with end-to-end encrypted cloud backup

Cognitive Vault

Your AI memory, owned by you — and it goes wherever you go.

Cognitive Vault is a local-first memory layer for AI. It sits between your AI client and any LLM, learns facts from your conversations, and injects them into future prompts — so every session picks up where the last one left off.

What makes it different:

• Local-first — memories live in a SQLite database on your machine. Fact extraction runs on local models. No account, no telemetry; nothing leaves your device by default.
• One memory, every AI — the same vault serves Claude, ChatGPT, Gemini, Claude Code, Cursor, or any OpenAI-compatible client and agent. Switch providers without your AI forgetting who you are.
• Encrypted cloud sync, strictly optional — sync across devices if you choose; the server only ever stores ciphertext. Your keys, your data.

No prompt engineering. Just start chatting.

Note: Encryption, cloud sync, cloud extraction, and cloud recovery are under testing and coming soon. The current release is fully local.

---

Principles

• Your memory, your data — AI memory is personal. It belongs to you, not to any platform or provider.
• Fully portable — your memories travel with you across Claude, ChatGPT, Gemini, or any future model. Switch providers without starting from zero.
• Privacy first — extraction runs locally by default. Your conversations never reach a server that could read, log, or train on them.
• Transparent and auditable — you can see, edit, and delete everything the AI remembers about you. No black box.
• Encrypted cloud sync — if you sync across devices, the server only ever receives ciphertext. Plaintext never leaves your machine.
• No training contribution — because nothing is sent to a central server, your data cannot be used to train anyone else's model.

---

How it works

Your AI client → http://127.0.0.1:4081 → Cognitive Vault → LLM API

1. Intercept — every conversation passes through the local proxy
2. Extract — after each session, a local model reads the transcript and pulls out facts about you
3. Store — facts are embedded and saved to a local SQLite vector database
4. Inject — on the next conversation, relevant memories are silently prepended to the system prompt

All data stays on your machine by default. Optional encrypted cloud backup syncs memories across devices — the server only receives ciphertext, never plaintext.

---

Requirements

• Python 3.12+
• Ollama for local fact extraction (free, runs on your machine)

---

Installation

git clone https://github.com/ssun/cognitive-vault
cd cognitive-vault
python3.12 -m venv .venv
.venv/bin/pip install -e .

---

Quick start

vault setup

The setup wizard:

1. Chooses your embedding backend — local ONNX model (~90 MB, downloaded once) or a remote Ollama host
2. Asks which extraction provider to use (local Ollama or Anthropic API)
3. Writes your config.toml

Then start the daemon and point your AI client at it:

vault start
export ANTHROPIC_BASE_URL=http://127.0.0.1:4081
claude   # or any other AI client

After a few conversations, check what was captured:

vault memory list
vault memory search "tools I use"

---

Built-in chat client

Cognitive Vault ships with a terminal chat client. No proxy setup required — it routes through the vault automatically.

vault chat            # start a new conversation
vault chat --continue # resume your most recent session

---

Platform setup guides

Platform	Guide
macOS	instructions/macos.md
Windows	instructions/windows.md

---

Key commands

vault chat                      # open the built-in TUI chat client
vault chat --continue           # resume last session
vault status                    # daemon status + memory count
vault memory list               # all stored memories
vault memory search "query"     # semantic search
vault memory sessions           # episodic session summaries
vault memory graph --format dot # export memory graph (Graphviz)
vault keys set anthropic <key>  # store an API key
vault stop / vault start        # daemon control

---

Configuration

vault setup writes a config file to your platform's app data directory:

Platform	Path
macOS	~/Library/Application Support/CognitiveVault/config.toml
Windows	%APPDATA%\CognitiveVault\config.toml

The config.toml in this repo is a documented template with all available options.

---

Extraction providers

Provider	Setup	Privacy
Local (Ollama)	ollama pull qwen2.5:3b	100% local, no API key needed
Anthropic (under testing)	vault keys set anthropic <key>	Conversation turns sent to Anthropic API

Default is local. Switch in config: extraction_provider = "anthropic".

---

License

AGPL v3 — see LICENSE.