Metadata-Version: 2.4
Name: cognitive-vault
Version: 0.1.0
Summary: Local-first AI memory layer with end-to-end encrypted cloud backup
Project-URL: Repository, https://github.com/ssun/cognitive-vault
Author: Steven Sun
License: AGPL-3.0-or-later
License-File: LICENSE
Keywords: ai,llm,local-first,mcp,memory,privacy,proxy,rag
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: GNU Affero General Public License v3 or later (AGPLv3+)
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.12
Requires-Dist: argon2-cffi>=23.1
Requires-Dist: cryptography>=42.0
Requires-Dist: httpx>=0.27
Requires-Dist: httpx[http2]>=0.27
Requires-Dist: keyring>=25.2
Requires-Dist: mcp>=1.0
Requires-Dist: mnemonic>=0.21
Requires-Dist: numpy>=1.26
Requires-Dist: onnxruntime>=1.18
Requires-Dist: pydantic>=2.7
Requires-Dist: rich>=13.7
Requires-Dist: sqlite-vec>=0.1.6
Requires-Dist: starlette>=0.37
Requires-Dist: textual>=0.61
Requires-Dist: tokenizers>=0.19
Requires-Dist: tomli-w>=1.0
Requires-Dist: tomllib>=2.0; python_version < '3.11'
Requires-Dist: typer>=0.12
Requires-Dist: uvicorn>=0.29
Provides-Extra: dev
Requires-Dist: aiosqlite>=0.20; extra == 'dev'
Requires-Dist: asyncpg>=0.29; extra == 'dev'
Requires-Dist: fastapi>=0.111; extra == 'dev'
Requires-Dist: httpx>=0.27; extra == 'dev'
Requires-Dist: mypy>=1.10; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
Requires-Dist: pytest>=8.2; extra == 'dev'
Requires-Dist: ruff>=0.4; extra == 'dev'
Provides-Extra: server
Requires-Dist: aiosqlite>=0.20; extra == 'server'
Requires-Dist: asyncpg>=0.29; extra == 'server'
Requires-Dist: fastapi>=0.111; extra == 'server'
Description-Content-Type: text/markdown

# 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.

![Cognitive Vault demo](https://raw.githubusercontent.com/ssun/cognitive-vault/main/cognitive-vault-demo.gif)

---

## 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](https://ollama.com) for local fact extraction (free, runs on your machine)

---

## Installation

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

---

## Quick start

```bash
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:

```bash
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:

```bash
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.

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

---

## Platform setup guides

| Platform | Guide |
|---|---|
| macOS | [instructions/macos.md](instructions/macos.md) |
| Windows | [instructions/windows.md](instructions/windows.md) |

---

## Key commands

```bash
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](LICENSE).
