Aurelius

Self-hosted knowledge graph memory for developers and AI agents.

Every AI session starts with full project context.
Decisions, problems, solutions — preserved across sessions.

---

The Problem

Every AI session starts from zero. You re-explain your projects, your past decisions, your architecture.

With Aurelius: memory_status → full picture. memory_session → nothing lost.

---

Quick Start

git clone https://github.com/Blysspeak/aurelius && cd aurelius
./install.sh

This builds binaries, installs to ~/.local/bin, configures Claude Code MCP server and hooks, initializes the database, and indexes the project. Restart Claude Code and you're ready.

$ au --version
au 1.1.0

---

MCP Tools (14)

Aurelius runs as an MCP server over stdio. install.sh configures it automatically, or add manually via /mcp in Claude Code (command: au, args: ["mcp"]).

Knowledge Graph

Tool	Description
memory_status	Session start — full project snapshot. Optional project filter.
memory_session	Session end — save decisions, problems/solutions, next steps. SHA-256 dedup.
memory_recall	Smart topic recall — FTS + BFS, grouped by type, skips structural noise.
memory_search	Full-text search with type, since, and limit filters. * for recent.
memory_context	Raw BFS graph traversal from FTS seed nodes.
memory_add	Create node with label, type, note, data (JSON), memory_kind.
memory_update	Update existing node's note/data by UUID or label.
memory_relate	Create typed edge. INSERT OR IGNORE for dedup.
memory_forget	Delete node by UUID (cascades to edges).
memory_gc	Garbage collection — duplicate edges/nodes, orphans.
memory_dump	Paginated graph export (offset/limit).
memory_index	Index project structure from Cargo.toml.

Web Search

Tool	Description
search_web	Brave Search API with SQLite cache. Repeat queries served from cache. Optional save_to_graph.
search_recall	FTS search through cached web search results from past sessions.

Requires a Brave Search API key (free: 2000 queries/month). install.sh prompts for the key, or add manually: echo 'YOUR_KEY' > ~/.config/aurelius/brave.key.

Session Lifecycle

Session start  →  memory_status(project: "myapp")
During work    →  memory_add, memory_relate (as needed)
Session end    →  memory_session(summary, decisions, problems_solved, next_steps)

---

CLI

au init                          # initialize database
au note "chose X over Y" -p app  # capture a decision → project
au context beacon                # graph around a topic
au search "redis"                # full-text search
au reindex                       # index current project
au view                          # open web graph UI
au touch path/to/file            # track file access
au export                        # export full graph as JSON
au mcp                           # start MCP server

---

Web UI

Interactive knowledge graph visualization with always-live Obsidian-style physics.

au view            # opens browser at localhost:7175
au view -P 8080    # custom port
au view --no-open  # don't open browser

Features: force-directed graph, color-coded node types, sidebar filters, node detail panel, search, drag interaction.

---

Architecture

crates/
  aurelius-core/
    src/graph/       — crud.rs, search.rs, traverse.rs
    src/db.rs        — SQLite setup, migrations V1-V5
    src/models.rs    — Node, Edge, NodeType, Relation, MemoryKind
    src/indexer.rs   — Cargo.toml project indexer
  aurelius/
    src/mcp/
      handlers/      — status.rs, session.rs, crud.rs, search.rs
      tools.rs       — MCP tool definitions (JSON schemas)
      mod.rs         — JSON-RPC 2.0 server
    src/search/
      brave.rs       — Brave Search API client
      cache.rs       — SQLite search cache with FTS5
  au/                — CLI + web UI server
ui/                  — React + TypeScript + Tailwind (graph visualization)
contrib/
  claude-code/       — session hooks (reindex, track edits)
  git-hooks/         — post-commit (captures decisions)

Key Design

• SQLite + WAL — concurrent reads, single writer, local-first
• FTS5 — indexes label + note (not raw JSON), kept in sync via triggers
• 5 schema migrations — V1 core, V2 access tracking, V3 indexes + edge dedup, V4 clean FTS, V5 search cache
• Batch BFS — WHERE id IN (...) per level, not N+1 per node
• Session dedup — SHA-256 content hash on (project, summary)
• Edge dedup — UNIQUE constraint on (from_id, to_id, relation)
• Problem lifecycle — unsolved = no Solution node with solves edge
• Relevance ranking — FTS results boosted by access_count
• Content hashing — SHA-256 for incremental re-indexing

---

Hooks (Auto-Capture)

Installed automatically by install.sh into ~/.claude/settings.json.

Hook	Event	What it does
aurelius-reindex.sh	Stop	Re-indexes project on session end
aurelius-track-edit.sh	PostToolUse (Edit/Write)	Increments access_count on file nodes
post-commit	git commit	Captures commit as Decision node, linked to project via belongs_to

---

Roadmap

• v0.1 — Core graph, CLI, MCP server (8 tools), project indexer, web UI
• v0.2 — Wildcard search, dump pagination
• v0.3 — Session memory, memory_update, enhanced memory_add
• v0.4 — Smart recall, type-filtered search, problem lifecycle, always-live graph
• v0.5 — Query optimization, session dedup, no double storage
• v1.0 — Project scoping, batch BFS, GC, edge dedup, FTS cleanup, modular codebase, install.sh auto-config
• v1.1 — Web search (Brave API + SQLite cache + graph integration), install.sh Brave key setup
• Next — Context-ranked search results, git log connector, auto-session via Stop hook

---

License

MIT