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;
以上为 README 的开头部分。其余内容请阅读原文。 查看完整 README ↗
