AsanagiDB-mcp

Modes

Quick Start

# local mode — AI tools point to http://localhost:8080
asanagidb-mcp

# connect to a central (remote) MCP server — Developer license required
asanagidb-mcp --central tcp://10.0.0.1:8443

# run as a federation server — mTLS is mandatory
asanagidb-mcp --public --http-port 8443

Flags

Document Memory (RAG)

Give asanagidb-mcp folders to read and an assistant can read your documents into the memory database, then search them before it answers. The graph keeps each document's structure: its sections, the concepts they mention, the facts and questions they answer, and how the concepts relate. It records where each section is in its file, never the text, so the assistant reads the exact words from your file when it needs them. Memories can point at document concepts (memory_save with about).

asanagidb-mcp --db-name memory --rag-folder ~/Notes --rag-folder ~/Projects/docs

Reads Markdown, plain text, reStructuredText, Org, AsciiDoc and TeX. PDFs are read by AsanagiDB Desktop. Files outside the folders you name are refused, symlinks included. Tools: rag_list_documents, rag_begin_document, rag_read_sections, rag_submit_concepts, rag_search, rag_forget_document, rag_status.

Memory notes can be documents too, with nothing exported to files. With --rag-memory decision,design,architecture, every note whose name has one of those words (decision_cache_policy, rope_design) is read like a file, as memory:<name>. When a note is saved with new text it lists as changed, so the assistant reads it again; rag_status counts the notes waiting to be read.

asanagidb-mcp --db-name memory --rag-folder ~/Notes --rag-memory decision,proposal,design,architecture

The server holds every assistant to the same reading rules: a section must be read with rag_read_sections before it is reported, a section of 300 characters or more needs 2 to 6 questions, a concept's kind comes from a fixed list (person, place, work, organization, system, event, era, topic, term, decision), and the reader names its model (extractor). A section that breaks a rule comes back with the reason, to be fixed and sent again. A document from a folder you no longer list shows as gone and can still be forgotten.

Config File

Instead of a long command line, put the settings in a JSON file and start the server with --config. The keys mirror the flags; paths may start with ~/. Flags given on the command line still win: a single flag replaces the file's value, and a folder or memory flag replaces the file's list. An unknown key stops the server, so a typo can't silently drop a setting.

{
  "db_path": "~/asanagi/memory",
  "http_port": 7474,
  "workspace": "Work",
  "rag_folders": ["~/Documents/Notes", "~/Projects/docs"],
  "rag_light_folders": ["~/Documents/Journal"],
  "rag_memory": "decision,proposal,design,architecture"
}

Keys: db_path, db_name, remote, central, http_port, public, cert_dir, sigil_url, workspace, rag_folders, rag_light_folders, rag_memory (a list, or one comma-separated string).

One Server, Many Assistants

If more than one assistant uses the same database at once — several Claude Code windows, Claude Code and Gemini, a person and an agent — run one asanagidb-mcp and let every assistant connect to it over HTTP. By default each session starts its own process over stdio, and all of them open the same --db-path.

# one server for every assistant; keep it running with your service manager
asanagidb-mcp --db-path ~/asanagi/data --http-port 7474

# then point each assistant at it (Claude Code CLI)
claude mcp add --scope user --transport http asanagidb http://127.0.0.1:7474

1. Quit every assistant session that uses the memory server.
2. Remove the old stdio entry for the same database from the assistant's settings. This is the step people skip: a stdio asanagidb-mcp still pointing at the same --db-path shares the database with the new server, which is the setup that hangs.
3. Start the server at login and restart it after a crash — a LaunchAgent with KeepAlive on macOS, a systemd user unit on Linux (untested), a service wrapper or scheduled task on Windows (untested).
4. Check the log says it is listening on 127.0.0.1, then start a new session and run a memory_search.

Do not set ASANAGIDB_MCP_HTTP_PORT for this: with it, each stdio process would try to open its own listener on the same port. The server binds 127.0.0.1 only (unless --public), and it has no token check on this path, so anything on the machine can reach the port.

A Note on --remote

Federation Architecture

AI Tool ──MCP (HTTP, plain)──► asanagidb-mcp (local, 127.0.0.1)
                                      │
                            --central tcp:// (mTLS)
                                      │
                                      ▼
                            asanagidb-mcp --public (remote MCP Server, 0.0.0.0)