Negotiated AI Memory

A chat interface where AI memory is negotiated by the user rather than accumulated silently. Users see what is being remembered as it forms, correct it, scope it to a session, and see which memories shaped each response.

HCI hackathon project (SIGCHI-supported). Design rationale is a first-class deliverable; the architecture notes, phase plan and decision log are kept alongside this repo rather than in it.

Backend status: production-ready. Authentication (Supabase JWT / Google), per-user data isolation, secrets handling for confidential-compute deployments, Docker, CI and a pytest suite are in place — see docs/DEPLOYMENT.md and docs/TEE.md.

Feature phase: P0, P1, P2, P3 and P6 complete — the whole demo spine. Say something, get a reply that shows which memories shaped it, correct the classification in one tap, drop a memory and watch the answer change, and ask for a high-stakes draft that refuses to write up unfinished work as finished. Remaining: P4 (complete list view), P7 (pre-send PII), P5 (deletion-preview graph), P8 (accessibility pass).

The design principles this is judged on are enforced in code, not just described — the table under Layout names the file each one lives in.

Read this before you demo. Chat and extraction run on OpenRouter :free model slugs, which are rate-limited per day and are retired without notice — three :free slugs 404'd during the port. If chat starts failing, check the slug is still listed before debugging anything else, and drop the :free suffix in LLM_CHAT_MODEL / LLM_EXTRACT_MODEL to fall back to the paid version. Embeddings have no free option, but cost fractions of a cent per session.

---

Production

docker compose up --build                                        # local stack: API + pgvector Postgres
docker compose -f deploy/docker-compose.prod.yml up -d --build   # secrets as files, read-only fs
make install && make db && make test                             # pytest suite against real Postgres

Activating Supabase, auth modes, env vars, health endpoints: docs/DEPLOYMENT.md. Keeping API keys inside a TEE (and what a TEE does not protect): docs/TEE.md.

Setup

Requires Python 3.11+, Node 20+, and a Postgres database with pgvector (this repo is developed against Supabase free tier).

cp .env.example .env        # then fill in DATABASE_URL and LLM_API_KEY

DATABASE_URL — Supabase dashboard → Connect. Use Direct connection if your network has IPv6, otherwise Session pooler (note the username becomes postgres.<project-ref>). Transaction pooler will not work — it breaks the prepared statements psycopg uses.

LLM_API_KEY — https://openrouter.ai/keys. OpenRouter is reached over its OpenAI-compatible API, so LLM_BASE_URL can point at any other compatible gateway without further code changes. This key also does extraction and embeddings, so it is effectively required.

GROQ_API_KEY and GEMINI_API_KEY are optional. Whichever are present appear in the composer's Model switcher, changeable mid-conversation. Switching changes only who writes the next reply — extraction and embeddings stay pinned, so the memory carries across providers rather than being re-derived (D32). Each reply is labelled with the model that wrote it.

# backend
python -m venv .venv
.venv/Scripts/python -m pip install -r backend/requirements.txt   # Windows
# .venv/bin/python -m pip install -r backend/requirements.txt     # macOS/Linux

.venv/Scripts/python backend/scripts/migrate.py                   # apply schema + seed

# frontend
cd frontend && npm install

Run

Two terminals:

# terminal 1 — API on :8000, docs at /docs
cd backend && ../.venv/Scripts/python -m uvicorn app.main:app --reload --port 8000

# terminal 2 — UI on :3000
cd frontend && npm run dev

Verify

.venv/Scripts/python backend/scripts/smoke_p0.py               # schema + API, no LLM calls
.venv/Scripts/python backend/scripts/smoke_p1.py               # 26 checks, the full loop
.venv/Scripts/python backend/scripts/leak_test_p3.py --no-llm  # store invariants, free
.venv/Scripts/python backend/scripts/leak_test_p3.py           # 18 checks, full leak test
.venv/Scripts/python backend/scripts/smoke_p2_p6.py --no-llm   # classifier truth tables, free
.venv/Scripts/python backend/scripts/smoke_p2_p6.py            # + CV failure case, revoke, decay
.venv/Scripts/python backend/scripts/migrate.py --status
curl http://127.0.0.1:8000/health

smoke_p1.py makes real LLM calls and draws against the daily free-tier allowance. Run it when you have changed the loop, not as a habit.

The two --no-llm modes are the ones to run in front of an audience: they are free, deterministic, and they carry the strongest evidence. leak_test_p3 --no-llm is a database query returning zero rows; smoke_p2_p6 --no-llm walks the overstatement detector across its whole truth table — including the row where a draft claims a paper is finished and the memory says otherwise, which the end-to-end run cannot reach because the model declines to overstate when asked to (D34).

After changing the embedding model — including the Gemini → OpenRouter port — re-embed the store:

.venv/Scripts/python backend/scripts/reembed.py --dry-run   # report only
.venv/Scripts/python backend/scripts/reembed.py             # rewrites the embedding column only

Embeddings from different providers occupy different vector spaces and mixing them fails silently — retrieval returns the wrong memories rather than erroring (D31).

To clear accumulated test memories without touching the schema:

-- Supabase SQL editor. Blocks and the demo user survive.
delete from attributions;
delete from memory_edges;
delete from audit_log;
delete from memory_items;
delete from messages;
delete from chats;

This is the beginning of the README. Read the rest at the original. Read the full README ↗