Strata

STRATA v2.2

This repository is superseded by [SOLUM](https://github.com/agenerationforwordz-tech/Solum).

SOLUM is the actively developed version of this project: PostgreSQL + pgvector instead of SQLite,

a larger tool set, and numerous fixes not present here. New users should start with SOLUM.

This repository remains available for reference.

Self-hosted AI memory server. Your thoughts, your hardware, your data.

Why Strata?

Your AI forgets everything the moment the session ends. Strata fixes that. It gives any MCP-compatible AI a persistent memory that lives on YOUR hardware - not in the cloud, not on someone else's server. Search by meaning, attach real files, and run it all on a Raspberry Pi.

What's new in v2.2

v2.0 taught Strata who's talking. v2.2 teaches it to scale, audit, and remember your past.

• Per-agent API keys - every AI agent gets its own key with granular read / write / delete / admin / kill permissions. You stop sharing one key across every tool. Manage them from /admin/agents.
• Global MCP kill switch - one toggle that locks every agent out of MCP, REST, and /api/*. Any agent with write or kill permission can pull the brake; only a human admin can flip it back on. Built for the moment a tool goes rogue.
• 3D Constellation viewer - watch your brain think in real time at /constellation. Sacred-geometry layout (Flower of Life background, dodecahedron clusters, Fibonacci sphere distribution), per-agent colors, live activity stream, and a kill-switch indicator that desaturates the whole scene when MCP is offline.
• Per-agent identity colors - each agent gets a color from a curated palette, editable from the admin panel. Colors flow through the constellation viewer so you can tell at a glance which agent is doing what.
• Encryption at rest (optional) - SQLCipher AES-256 encryption with key in a root-only file. Dormant by default; flip on with one env var and a setup script when your threat model needs it.
• File-level hardening (optional) - dedicated strata system user owns the database with mode 600. SSH users can no longer bypass the API by editing the SQLite file directly.
• Demo mode - run a public demo with STRATA_DEMO_MODE=true and the dashboard accepts blank passwords (the login screen still renders so visitors can see the auth feature exists).

New in v2.2:

• PostgreSQL + pgvector backend — SQLite is still the default for quick demos, but set STRATA_DB_BACKEND=postgresql for production. PostgreSQL handles concurrent multi-agent writes natively (no more write queue), and pgvector does similarity search IN the database with HNSW indexes. Scales to 1 million+ thoughts.
• CSV audit log — every agent action is logged to daily CSV files in data/audit/. Full replay tape: who searched what, which thoughts came back, how long it took. This is the transparency layer — trace exactly how an AI built its understanding of your data. View via GET /api/audit.
• Pre-Strata history (negative IDs) — import your memories from BEFORE you installed Strata using capture_legacy. These get negative IDs (-1, -2, -3...) and live in the same constellation alongside your current thoughts. Your AI memory doesn't start at install day — it reaches back as far as you want. Click "THOUGHTS" in the constellation viewer to toggle between current and historical views.
• 10 thought types — expanded from 8 types with clear descriptions that teach AI agents WHEN to use each one. Added idea (brainstorms, not yet decided) and observation (patterns noticed, no conclusions drawn). The agent protocol now spells out type selection so every new user's constellation is balanced.
• Updated agent protocol — strata_status now teaches agents about all 10 types, negative ID history, the audit log, and outcome loop tracking. No CLAUDE.md needed — the protocol IS the onboarding.
• Constellation camera fix — clicking a star flies the camera past it and looks back, keeping the origin star visible in the background as an anchor.
• Demo mode improvements — agent creation and MCP kill switch now work without an admin key in demo mode.

Plus the v1 features you already know: semantic search, file vault, dedup protection, password+seed-phrase dashboard auth, dark theme, runs on a Pi.

I built this because I got tired of my AI tools forgetting everything between sessions. STRATA gives any MCP-compatible AI (Claude Code, Codex CLI, whatever comes next) a persistent brain that lives on YOUR machine. Not in the cloud. Not on someone else's server. Yours.

It runs on a Raspberry Pi 4B. Seriously. The whole thing - semantic search, file storage, embeddings - runs on a $55 computer with 4GB of RAM.

What it does

• Search by meaning - ask for "money stuff" and it finds your notes about Bitcoin, investments, and budgets. Not keyword matching. Actual understanding.
• File vault - attach real files to your thoughts. Code, documents, project archives. The thought is your index, the vault holds the goods.
• Auto-tagging - write about Docker? It tags it. Mention a URL? Tagged. You don't have to organize anything manually.
• Dedup protection - tries to save something you already saved? It catches it and warns you.
• Access tracking - see which memories actually get used vs which ones just sit there.
• Admin-only deletion - AI can read and write memories, but it CANNOT delete anything without your explicit admin key. Your data, your control.

Why I built it this way

Regular databases search by keywords. If you stored "switching careers" but search for "new job", you get nothing.

STRATA converts every thought into a 768-dimensional vector that captures what it *means*. Similar ideas land near each other in that vector space. So "switching careers" and "new job" and "career change" all find each other.

The model runs locally through ONNX Runtime (not PyTorch - that thing eats 1.5GB just to import on ARM). Total RAM for the embedding model is about 100-150MB, and it unloads after 5 minutes of idle time.

The file vault

This is what makes STRATA more than a note-taking app.

You capture a thought about a project. Then you attach the actual source files to it. Later, when you or your AI searches for that topic, you get the thought AND a list of every file attached to it. The AI picks which files it needs and pulls just those - it doesn't load your whole drive into memory.

Files are organized on disk like this:

data/vault/

my-laptop/ 2026-03/ 42/ server.py config.py my-desktop/ 2026-03/ 55/ training_data.csv

Organized by device and month. You can browse it manually if you want. Files up to 1GB, text files capped at 5MB when returned to AI (so it doesn't blow up the context window).

Pre-Strata history (negative IDs)

Your AI memory doesn't have to start at install day. Import your past:

# Via MCP tool

capture_legacy( content="Decided to self-host everything after the cloud bill hit $400/mo", thought_type="decision", tags=["infrastructure", "self-hosting"], original_date="2024-06-15", source="pre-strata" )

Legacy thoughts get negative IDs (-1, -2, -3...) while live thoughts use positive IDs. Both are fully searchable — they live in the same vector space. The constellation viewer has a toggle: click "THOUGHTS" to dim current stars and highlight your history.

CSV audit log

Every agent interaction is logged to daily CSV files in data/audit/:

data/audit/

audit_2026-04-19.csv audit_2026-04-20.csv ...

Each row records:

• timestamp — when the operation completed (UTC)
• agent_name — which agent made the call
• agent_key_hint — masked API key (enough to identify, not enough to use)
• action — what happened (capture_thought, semantic_search, etc.)
• detail — search query or content preview
• thought_ids — which thoughts were touched
• result_count — how many results came back
• response_ms — operation duration

Query today's log via REST: GET /api/audit?limit=50

Override the directory: STRATA_AUDIT_DIR=/your/path Disable entirely: STRATA_AUDIT_ENABLED=false

PostgreSQL backend (production)

SQLite works great for getting started and single-user setups. For production with multiple agents hitting Strata simultaneously, switch to PostgreSQL:

# Install PostgreSQL 17 + pgvector

sudo apt install postgresql-17 postgresql-17-pgvector

Create the database and user

sudo -u postgres createuser strata sudo -u postgres createdb strata_db -O strata sudo -u postgres psql -c "ALTER USER strata PASSWORD 'your-password-here';"

Run the schema (creates tables, indexes, triggers)

sudo -u postgres psql -d strata_db -f strata_pg_schema.sql

Set the backend

export STRATA_DB_BACKEND=postgresql export STRATA_PG_PASSWORD=your-password-here

Start Strata — it auto-detects the backend

python server.py

Migrating from SQLite to PostgreSQL

If you already have thoughts in SQLite:

python migrate_to_pg.py

This migrates all thoughts, embeddings, history, agent keys, and profiles. Your SQLite database is preserved as a backup.

Why PostgreSQL?

Try the demo first (60 seconds, no setup)

The repo ships with a pre-populated demo database: 666 curated thoughts about Strata itself, 3 sample agents with palette colors, ready to explore. No mining, no seed data hunt, no thinking about what to capture first — just clone, drop the demo DB into place, and see the constellation populated.

git clone https://github.com/agenerationforwordz-tech/strata.git

cd strata

python -m venv venv source venv/bin/activate # Windows: venv\Scripts\activate pip install -r requirements.txt

Drop the curated demo dataset into place

mkdir -p data cp demo/strata.db data/strata.db

Run with demo mode so blank passwords work for visitors

STRATA_DEMO_MODE=true python server.py

⏱️ First install takes 5–15 minutes. pip install -r requirements.txt downloads about 700 MB of binary wheels for the embedding model runtime (fastembed, onnxruntime, numpy, transformers tokenizer support). Don't kill the install if it appears stuck — it's downloading binaries in the background. Subsequent installs reuse the venv and take seconds. Run with pip install -r requirements.txt --progress-bar on if you want to watch the byte count tick up.

Open these in your browser:

See demo/README.md for the full demo dataset details, including how to regenerate your own.

Windows install notes

A few Windows-specific gotchas worth knowing about:

• Git "dubious ownership" error on the D: drive. If you clone Strata to D:\ or any non-system drive, Git may refuse to operate on the repo with fatal: detected dubious ownership in repository. Fix:

  git config --global --add safe.directory 'D:/Claude Code Projects/strata'

(Replace the path with wherever you cloned.)

• **PowerShell env vars use `$en