---

🇺🇦 Читати українською

Why Litopys?

Memory systems for AI agents today force a tradeoff: either heavy vector databases with subprocess leaks and ~500 MB RAM footprint, or flat markdown files that don't scale past a few dozen notes.

Litopys takes a third path: a typed graph of knowledge stored in plain markdown, served through a thin MCP layer (~75 MB RAM), editable by hand, queryable by both keyword and structure. Litopys means "chronicle" in Ukrainian — because that's exactly what your AI's memory should be: a living record of what it learned about you, when, and why.

Features

• 🧠 Typed graph — 6 node types (person, project, system, concept, event, lesson) with 11 first-class relations
• 🕰 Bi-temporal queries — every node carries event time (occurred_at, since, until) independent of when the file was last written; ask "what was true on date X?" via the as_of parameter (see docs/temporal-model.md)
• 🔌 MCP-native — works with Claude Code, Claude Desktop, Cursor, Cline, or any MCP client (see docs/integrations)
• 📝 Markdown-first — every node is a plain .md file with YAML frontmatter. Hand-editable, grep-able, git-versioned
• 🧹 Graph maintenance — litopys evolve archives tombstoned nodes (with an auditable manifest) and auto-applies high-confidence merge proposals from quarantine (see docs/memory-evolution.md)
• 🤖 Model-agnostic extractor — Anthropic, OpenAI, or local Ollama. Pick by your resource/cost budget (see Resource footprint below). Facts flow through a quarantine so nothing lands unreviewed
• 🌐 Web dashboard — browse, search, edit, visualize the graph, and review quarantine at http://localhost:3999
• 🔐 Stays local — graph lives in ~/.litopys/graph/ as files; the server binds to 127.0.0.1 by default; no telemetry

Dashboard

Screenshots taken against a synthetic demo graph bundled in docs/screenshots/ — not the author's personal notes.

Status

v0.2.0 is out — bi-temporal model (occurred_at / since / until on every node, as_of queries), litopys evolve maintenance command (archive tombstoned nodes, auto-merge high-confidence proposals), and a new @litopys/bench benchmark harness with a deterministic mock extractor — see the CHANGELOG. Prebuilt binaries for Linux / macOS / Windows (x64 + arm64), with SHA-256 checksums verified by install.sh. Test suite at 613 / 613 pass. Public surfaces (MCP tools, CLI, JSON export schemaVersion: 1, on-disk markdown layout) remain backward-compatible; further breaking changes will ship as 0.3.x.

Core graph, MCP server (5 tools, stdio + HTTP/SSE), extractor + quarantine + weekly digest, timer-daemon, dashboard (read + write + graph viz + quarantine review), identity-resolution guardrails, single-binary build, one-line installer, per-client integration docs — all shipped. See What's next for the planned follow-ups.

Resource footprint

Honest numbers from the author's own install (Ubuntu, Bun 1.x). The MCP server is cheap; the extractor is where the bill shows up, and it depends on which adapter you pick.

Component	RAM	When it costs
MCP server (stdio or HTTP)	~75 MB	always, while a client is connected
Viewer / web dashboard	~50 MB	optional, only while running
Extractor — Anthropic / OpenAI	0 locally	per API call (tokens), no local RAM
Extractor — Ollama + 3B model	~2–3 GB	only during a tick, unloaded after
Extractor — Ollama + 7B model	~5 GB	only during a tick, unloaded after

So the minimum resident cost is ~75 MB for the MCP server. Extraction is optional — you can run Litopys read/write-only from your agent and never start the daemon. If you do enable extraction, the local-Ollama route trades cash for RAM; the Anthropic/OpenAI route trades RAM for cents per session. Ollama's keep_alive means the 3B/7B figures are transient — the model drops out of RAM a few minutes after the tick finishes.

Benchmark

@litopys/bench is an end-to-end harness that runs Litopys against a dataset of question/answer sessions and scores retrieval against expected node ids. The built-in synthetic dataset (15 questions, deterministic mock extractor) yields Recall@5 = 0.98, Precision@5 = 0.32, mean latency 4 ms. The synthetic fixture exists to validate the harness itself; adapters for real industry datasets (LongMemEval, LOCOMO) are a follow-up. See docs/benchmark.md for dataset format, metric definitions, and how to plug in new adapters.

Quick Start

One-line install (Linux / macOS):

curl -fsSL https://raw.githubusercontent.com/litopys-dev/litopys/main/install.sh | sh

This downloads a single ~100 MB binary to ~/.local/bin/litopys, initializes ~/.litopys/graph/ with the required subdirectories, and prints MCP registration hints.

Pin a specific version by placing the assignment after the pipe — env vars set before curl only scope to curl itself, not the piped shell:

curl -fsSL https://raw.githubusercontent.com/litopys-dev/litopys/main/install.sh | LITOPYS_VERSION=v0.2.0 sh

Then register the MCP server with your client:

# Claude Code
claude mcp add litopys -- ~/.local/bin/litopys mcp stdio

// Claude Desktop — ~/Library/Application Support/Claude/claude_desktop_config.json
{
  "mcpServers": {
    "litopys": {
      "command": "/home/you/.local/bin/litopys",
      "args": ["mcp", "stdio"]
    }
  }
}

Restart the client. The litopys://startup-context resource auto-loads the owner profile, active projects, recent events, and key lessons on every new session. The agent reads/writes through five MCP tools: litopys_search, litopys_get, litopys_related, litopys_create, litopys_link.

Full client-specific recipes live in docs/integrations/ — Claude Code, Claude Desktop, Cursor, Cline, ChatGPT Connectors, Gemini.

Remote (HTTP/SSE) mode

For remote clients (Claude Desktop connectors, browser-based MCP hosts):

LITOPYS_MCP_TOKEN=your-secret litopys mcp http
# listens on 127.0.0.1:7777 by default
# set LITOPYS_MCP_BIND_ADDR=0.0.0.0 + TLS proxy for remote exposure
# set LITOPYS_MCP_CORS_ORIGIN=https://your-client to enable CORS

Dev install (from source)

git clone https://github.com/litopys-dev/litopys.git
cd litopys
bun install
bun run build:binary       # produces dist/litopys

Optional — daemon for long-running transcripts

cp packages/daemon/systemd/litopys-daemon.{service,timer} ~/.config/systemd/user/
systemctl --user enable --now litopys-daemon.timer

Optional — web dashboard autostart

The dashboard (litopys viewer) can run as a systemd user service so it comes back after every reboot.

litopys viewer install        # generates token, writes unit, enables service
litopys viewer install --lan  # same + binds to 0.0.0.0 for LAN access
systemctl --user status litopys-viewer

# Remove:
litopys viewer uninstall

Access token. viewer install generates a random token automatically and saves it to ~/.litopys/viewer.token. The install output prints a ready-to-use URL with the token embedded:

✓ litopys-viewer installed

  Open dashboard:    http://localhost:3999/?token=<token>
  Share with others: http://192.168.1.x:3999/?token=<token>   # --lan only

  Opening the link once saves the token — no re-entry needed.
  Retrieve token later: cat ~/.litopys/viewer.token

Opening the URL once saves the token in localStorage — no further prompts. To share write access with someone, send them the URL that includes ?token=…. To retrieve the token at any time: cat ~/.litopys/viewer.token.

GET endpoints (browse, search, graph view) are always open. Mutating endpoints (create / edit / delete nodes, accept-or-reject quarantine) require the token.

Or set LITOPYS_ENABLE_VIEWER=1 when running install.sh to enable it as part of the one-line install. Requires loginctl enable-linger $USER if you want the dashboard to stay up across logouts.

Optional — Notion sync

@litopys/notion-sync reads your recently edited Notion pages via the Notion REST API, passes them through the configured LLM extractor to identify knowledge candidates, and writes the results to quarantine for review. A state file ~/.litopys/notion-sync.json tracks the last-sync timestamp so incremental runs only fetch pages modified since the previous sync.

# Set your Notion integration token
echo 'NOTION_TOKEN=secret_...' >> ~/.litopys/.env

# Run once to test
NOTION_TOKEN=secret_... litopys notion-sync

# Or install as a systemd timer (runs every 6 hours)
cp packages/notion-sync/systemd/litopys-notion-sync.{service,timer} ~/.config/systemd/user/
systemctl --user enable --now litopys-notion-sync.timer

Create the integration token at notion.so/my-integrations and share the pages or databases you want synced with the integration.

Extractor — self-hosted OpenAI-compatible endpoints

The extractor now supports any OpenAI-compatible server — vLLM, LM Studio, LocalAI, Ollama's /v1 proxy — via two environment variables:

LITOPYS_EXTRACTOR_PROVIDER=openai \
LITOPYS_EXTRACTOR_BASE_URL=http://myserver:8080/v1 \
litopys ingest ~/.claude/projects/.../*.jsonl

When LITOPYS_EXTRACTOR_BASE_URL is set and no API key is provided, authentication is skipped automatically — no dummy key needed. Use LITOPYS_EXTRACTOR_API_KEY to pass a key without overwriting the global OPENAI_API_KEY.

Agent skill — richer graph behavior (Claude Code)

The MCP connection gives Claude the 5 tools and 5 baseline rules. For full graph discipline — mandatory traversal after every search, supersedes chain awareness, write decision tree, temporal tombstoning — install the bundled skill:

cp -r skills/litopys-memory ~/.claude/skills/

Then open ~/.claude/skills/litopys-memory/SKILL.md and replace the placeholder trigger description with the actual project and system names from your graph — run litopys startup-context to see them.

Without the skill, Claude Code uses Litopys correctly but shallowly: it searches but rarely traverses edges, and may miss supersedes patterns that mark stale nodes.

Integrity check

litopys check           # human-readable report, grouped by error kind
litopys check --json    # { nodeCount, edgeCount, errorCount, errors[] } for CI

Loads and resolves the entire graph, then flags broken refs, duplicate ids, wrong-typed relations, and parse/validation failures. Exits non-zero when issues are found — drop it into a git pre-push hook or CI step so drift never lands silently.

Backing up your graph

Litopys stores everything as plain markdown in ~/.litopys/graph/, so any tool that versions files works. Two common approaches:

Git + private remote (incremental history, offsite, free):

cd ~/.litopys
git init
git add graph/ .gitignore README.md
git commit -m "baseline"
gh repo create my-litopys-graph --private --source=. --push

From then on, every session-end hook or manual accept leaves your working tree dirty — periodically git add -A && git commit -m "sync" && git push to keep the backup current. Your graph contains personal facts, so keep the remote private.

JSON snapshot (portable, diffable, tool-friendly):

litopys export > graph.json              # compact
litopys export --pretty > graph.json     # indented, VCS-friendly
litopys export --no-body > meta.json     # metadata only, strip markdown bodies

The dump carries meta (exportedAt, counts, schemaVersion) plus all nodes sorted by id and edges sorted by (from, relation, to) — deterministic across runs, so diff graph-yesterday.json graph-today.json tells you exactly what the LLM/daemon added. Feed it to analysis tools, migrate between hosts, or commit alongside code.

Restore from a snapshot on a fresh host (or after a reinstall):

litopys import graph.json --dry-run   # preview the plan
litopys import graph.json             # create new nodes, skip existing ones
litopys import graph.json --force     # also overwrite existing ids

Default is conservative — existing nodes are never touched unless you pass --force. Every node is validated against the schema up-front, so a corrupt snapshot aborts before anything lands on disk.

What's next

• Real benchmark adapters. @litopys/bench currently ships only a synthetic 15-question fixture. Next step is concrete adapters for LongMemEval and LOCOMO so the numbers become directly comparable to other memory systems.
• litopys evolve --restore. The archive manifest (archive/manifest.jsonl) records every tombstoned node moved to archive/ with its original path. A --restore <id> flag will replay a single entry in reverse so archived nodes can be brought back without leaving the CLI.
• Vector search. Considered and deliberately skipped — the keyword + typed-graph traversal model has been good enough in practice, and adding an embedding index would re-introduce the heavy footprint Litopys was designed to avoid. We'll revisit only if a concrete recall gap on a real benchmark dataset shows up.

Release history

See CHANGELOG.md. Beyond the What's next items above, future work is driven by real-user feedback — open an issue if something pinches.

Design principles

• Agent-agnostic. No hard dependency on any LLM vendor or client. MCP is the only integration point. Ollama is the default extractor; Anthropic/OpenAI are optional adapters. The extractor also supports any self-hosted OpenAI-compatible server (vLLM, LM Studio, LocalAI, Ollama /v1 proxy) via LITOPYS_EXTRACTOR_BASE_URL.
• Portable data. The graph is plain markdown + YAML frontmatter on disk. Readable in any editor, versionable in git, greppable from the shell.
• Light runtime. ~75 MB RAM for the MCP server. The extractor is out-of-process and runs on your schedule, not on every request — see Resource footprint for the full cost breakdown across adapters.
• Opt-in integrations. Client-specific helpers (hooks, config snippets) live in docs/integrations/ — you can use Litopys without any of them.

License

MIT © 2026 Denis Blashchytsia and Litopys contributors.