# Shared AI Memory Hub

A self-hosted shared memory server for AI assistants, with a calm, private GUI for the person in charge.

Keep Markdown memories, assistant handoffs and reusable skills in one Git-backed workspace. Read the same context from Codex and Claude, inspect every revision, compare conflicting edits, and review deletion requests before they take effect.

The interface preserves the original green-and-cream design, responsive sidebar and mobile navigation, dark mode, document reader, search, editor and history panels. The public edition uses English labels and fictional examples.

![Desktop preview with fictional data](docs/images/desktop.png)

## Try the GUI

Requires Python 3.12+, Node.js 20.19+ or 22.12+, npm, and Git on macOS or Linux. Native Windows is not supported because storage uses POSIX file locking and Unix sockets; use Linux or WSL2.

```sh
python3.12 -m venv .venv
. .venv/bin/activate
pip install -r requirements.lock
pip install -e '.[test]'
cd web
npm ci
npm run build
cd ..
python -m memory_mcp.demo
```

Open `http://127.0.0.1:8789`. This preview contains only fictional data, runs on loopback, needs no credentials, and deletes its temporary workspace on exit. It demonstrates the GUI; it does not provide authenticated MCP access. Run from the source checkout so the examples are available.

## Connect your assistants

For a real installation, follow [Quickstart and deployment](docs/quickstart.md). The service verifies OAuth JWTs and exposes separate `/mcp/read` and `/mcp/write` endpoints. The GUI travels over a private Unix socket behind an authenticated Tailscale Serve boundary.

You can ask Codex or Claude Code to set it up using the [assistant setup prompt](docs/assistant-setup.md). That guide explains which steps the assistant can complete and where you must choose your own domain, identity provider and login.

## Included

- Markdown documents with sources, aliases and explicit `[stated]` facts.
- Version checks that prevent silent overwrites, Git history and deliberate restoration.
- Literal full-text search, document links and backlinks, handoff dashboard.
- Read-only and write-enabled MCP tool catalogs with an owner subject allowlist.
- Private owner editor, diff view and review queue for deletions and major skill changes.
- On-demand skill sections, attachments and ZIP export. Reading scripts never executes them.
- No model API key or paid embedding service required by the hub itself.

## Documentation

- [Architecture](docs/architecture.md)
- [Quickstart and deployment](docs/quickstart.md)
- [Let an assistant help](docs/assistant-setup.md)
- [Security and privacy](SECURITY.md)
- [Dependency licensing](THIRD_PARTY_NOTICES.md)
- [Release checks](docs/release-checklist.md)

## Development

```sh
python -m pytest -q
cd web
npm ci
npm run build
```

Some backend tests deliberately retain Unicode text to cover multilingual search and privacy rules. These are synthetic fixtures. Browser tests use synthetic data; see the quickstart for the fixture and commands. Nothing in this repository needs access to the original installation.

## License

Original project code is licensed under [MIT](LICENSE). Dependencies keep their own licenses and notices. See [Third-party notices](THIRD_PARTY_NOTICES.md).