akasha-mcp
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
akasha
A local knowledge base that gives coding agents a memory, served over MCP.
The problem
Every agent session starts from zero. Yesterday an agent spent an hour working out why a test fails one run in twenty: two tests share a fixture directory and the cleanup of one races the setup of the other. It fixed the test and the session ended. The reasoning lived in a context window, and the window is gone. Today another agent meets the same flake, reads the same files and derives the same answer, spending the same time and context to get there.
What you already know is not missing, it is scattered. Some of it sits in Claude Code project memory, some in Serena memories, some in a notes folder, some in markdown files inside repos. Each agent writes to its own corner, and none of them searches the others. Pasting notes into prompts does not scale: context is the scarce resource, and every pasted page crowds out the work. Conventions ("migrations are reviewed before merge", "never mock the database in integration tests") get retyped at the start of session after session.
Related MCP server: RepoRecall
How akasha fixes it
akasha builds one local index over the markdown you already have. It is read-only by default and copies nothing: your files stay the source of truth, and the SQLite index derived from them can be deleted and rebuilt at any time.
Agents search it through MCP before they start investigating, and write what they find
back as ordinary markdown with knowledge_write and knowledge_append. The next
session starts where the last one ended. Search is keyword (BM25) and, if enabled, dense
retrieval, fused by reciprocal rank. Results are sized for a context window: a handful of
capped hits, with knowledge_get to get a long document as an outline and then one of its
sections, only when one is worth reading.
Conventions are documents of kind=convention. They are delivered automatically at
session start and are read-only to agents; only the CLI can create or change one. Hooks
keep the index fresh without anyone thinking about it (in Claude Code and Gemini CLI): a
session-start hook refreshes it in the background, and a post-tool hook reindexes a note
the moment an agent edits it.
Safety is enforced where the data enters. At index time, secret-shaped strings are redacted and known prompt-injection patterns are neutralised before any agent sees the text. Both are pattern-based: they catch the common shapes, not every secret. Destructive operations are CLI-only; an agent can archive a document, never delete one. There is no account and no server, and nothing leaves your machine (the one exception is a small embedding model, downloaded once if dense search is on).
A day with akasha: an agent running in claude records the flaky-test cause with
knowledge_write. The next morning an agent in gemini is asked about the same flake,
calls knowledge_search first, and finds the finding in one hit instead of an hour of
investigation.
Requirements
Python 3.11+ and uv
A supported agent CLI:
claude,geminiorcopilot.akasha init --allregisters with whichever are on your PATH. Any other MCP client can runakasha serve(stdio) by hand.
Install
The PyPI package is akasha-mcp; the command it installs is akasha.
uv tool install --python 3.12 'akasha-mcp[vectors]'--python matters when your default Python is older than 3.11 (macOS ships 3.9): uv does
not pick an interpreter from the package's requirement on its own, and downloads 3.12 if
you don't have it. Without dense search: uv tool install --python 3.12 akasha-mcp. From git:
uv tool install --python 3.12 'akasha-mcp[vectors] @ git+https://github.com/anuress/akasha'With [vectors] installed, akasha init writes provider = "model2vec" and search is
dense plus keyword. Without it, search is keyword-only: init says so and akasha doctor
keeps saying so. akasha config set embeddings.provider none turns dense search off. An
existing config is never rewritten; to enable it there, set embeddings.provider model2vec
and run akasha index.
Optional: pi
pi users can add the pi-akasha extension
(pi install git:github.com/anuress/pi-akasha). It registers the MCP server and runs
both hooks, including after compaction. akasha init --all does not configure pi.
Quickstart
akasha initCreates ~/.akasha/ (mode 0700) with config.toml, the SQLite index and a knowledge/
directory for documents agents write. On first run it looks for existing notes to index:
Claude Code project memories (~/.claude/projects/*/memory), and .serena/memories and
graphify-out directories in the immediate subdirectories of ~ (change with
--code-root DIR, repeatable).
akasha init --allRegisters the MCP server with every detected agent CLI through that CLI's own mcp add
command (copilot: its mcp-config.json), and installs the two hooks for claude and
gemini. For claude it also allows the mcp__akasha tools in settings.json so they do
not prompt; skip that with --no-allow. --dry-run prints what would be written and
changes nothing.
akasha index # build or refresh the index
akasha knowledge search "cache expiry" --limit 3
akasha doctor # what is degraded; exit 0 means healthySearch defaults to the repo of the current checkout; --all searches every repo.
Tools
Fourteen MCP tools:
Tool | What it does |
| Ranked chunks; current repo first, OR retry when strict finds nothing, |
| One document by id; a long one as an outline plus the sections your search hit, |
| New document; lists fold candidates and can supersede older ones |
| Correct a document in place, whole body or one exact span |
| Append a dated section to a document |
| Hide from default search; reversible |
| Integrity check, read-only |
| Documents in the order written |
| Linked documents: citations and backlinks |
| How many documents carry a feature tag |
| What is degraded about the installation |
| Feed a .csv/.xlsx export as a searchable dataset; reports what changed |
| One dataset row by |
| Filter rows: |
Feeding files
An exported sheet becomes a dataset: one document plus the stored copy its cells were split
from. Every non-empty cell of a kept column is its own chunk, so search finds the cell, and
the hit carries unit (dataset, locator, key, field) with the exact next call that reads
the whole row.
akasha feed add fruits.csv --as fruits --key idThe first feed prints first feed: N units. Feeding the same name again replaces its rows
and reports what changed: +A -R ~C, then one line per row, with a changed cell shown as
color: -red and color: +green. An eight-data-row fruits.csv prints first feed: 8 units
the first time and, once one row was added and two rows changed, +1 -0 ~2 the next: the
line counts rows added, removed and changed, not cells. The listing stops at 50 rows with
… N more (use --full); --full prints every row and every change line of a cell. A feed
that changes nothing prints unchanged.
A row is addressed two ways: row:N is its place in the export (row:2 is the first data
row under a header on row 1), and key:V is the value of that row's --key. A key value
is usable as a locator only when it is non-empty and unique among the rows the feed kept, and
--require decides which those are: a blank or repeated key leaves the row addressable as
row:N alone, and the feed warns once, naming the column.
akasha feed list
akasha feed get fruits key:3
akasha feed query fruits --where season=summer --fields name,colorfeed list: name, repo, units, feed date and copy path of every dataset.feed get: one row;--jsonprints it as an object.feed query:F=vmatches a whole cell,F~va cell containing the value, both case-insensitive; every--wheremust match.--limitdefaults to 20 (max 100).
Settings live on feed add:
Flag | Effect |
| Column whose value addresses a row across feeds; a first feed needs one |
| xlsx sheet; the first sheet unless one is named |
| Row holding the column headers (default 1) |
| Keep only rows with a value in this column (repeatable) |
| Drop this column's cells (repeatable); |
| Row label with |
Any setting flag replaces the whole stored settings object, so a re-feed that leaves --key
out is a feed whose rows are addressed by row number again; feed add prints
settings replaced: ... when it happens. With no setting flag at all, the last feed's
settings are reused.
--repo NAME feeds under a repo other than the one the current checkout resolves to;
--repo '*' is refused, because a dataset belongs to one repo. The name is global to the
installation, so feeding one name under a second repo is refused rather than quietly
divergent: use another name, or feed rm the first one.
The copy is ~/.akasha/files/<repo>/<name>.<ext>, the document is
~/.akasha/knowledge/<repo>/datasets/<name>.md. The cells are split from that copy, so
re-feeding replaces it.
xlsx needs an extra:
uv tool install --python 3.12 'akasha-mcp[xlsx]'Without it the splitter names the extra, and doctor reports it for as long as an xlsx
dataset exists.
The document is generated: knowledge update, knowledge append, knowledge archive
and knowledge rm refuse it and point at feed add; akasha feed rm fruits moves
document and copy to the trash and prints the id knowledge restore takes. A restore is
refused while a dataset of that name is live, and knowledge purge deletes trashed copies
too.
In detail: fsck reports a copy that is missing or edited (error), units that no longer
match the copy (warning; akasha index --force repairs them), damaged metadata, a copy no
readable document names, and a staging or backup file an interrupted feed left behind.
doctor reports the last failed attach of a dataset whose units are still not its own, and
the xlsx extra while an xlsx dataset exists. Search keeps answering from the units already
stored while either is unresolved, which is why the finding names the re-feed that fixes it.
Hooks
Two hooks, both fail-open (they never block a session or a tool):
akasha hook session-startprints the repo's conventions, a short brief and an integrity note into the new session. The installed command passes--defer-refreshso it does not wait for an index walk.akasha hook post-toolreads the tool payload on stdin and reindexes the one file an agent just wrote, if it is inside an index root. After 15 edits in a session with nothing recorded throughknowledge_write,knowledge_appendorknowledge_update, it prints a one-time reminder to record what was learned; the count restarts at the next write. It also prints thekind=gotchadocuments scoped to the file, as context after the edit (advisory; never blocks). A gotcha opts in with frontmatterpaths: [globs], matched against the path relative to the file's checkout (*stays in one directory,**crosses them; braces are not supported), and may addpattern: <regex>, which must match the new text (keep it simple; only the first 200,000 characters are scanned). Repo-scoped anddefaultgotchas apply; each is shown once per session per file.
Documents of kind=convention are standing rules: they are injected at session start and
are read-only over MCP. Only the CLI can create or change one.
Sources and config
The native knowledge directory (~/.akasha/knowledge) holds documents written through
akasha. Everything else is an indexed root, one [[index]] block in config.toml:
[[index]]
path = "~/notes"
source = "notes"
include = ["**/*.md"] # optional globs
exclude = ["**/cache/**"]
repo = "my-repo" # repo the whole root belongs to
writable = false # default; true lets knowledge_append write into itRoots are read-only by default. Add one without editing the file:
akasha index add ~/notes --source notes --repo my-repo
akasha indexDeleting things
Agents can only archive. Everything else is CLI-only.
Command | Effect |
| Hidden from default search; reversible with |
| Moved to trash; recoverable |
| Brings a trashed document back |
| Permanently deletes trashed documents ( |
Rebuilding and ids
The database is derived from the files:
rm ~/.akasha/akasha.db && akasha indexIds of documents in indexed roots are derived from root and relative path, so links between documents survive a rebuild. Moving or renaming a file changes its id.
Privacy
At index time, secrets are redacted (scan_secrets, on by default) and prompt-injection
shapes are neutralised before text reaches an agent; common secret files (.env*, *.pem,
*.key, *.pfx, *.kdbx, SSH keys, .npmrc, .pypirc, credentials.json and similar)
are denied outright; deny_files and deny_extensions in [security] replace the lists.
A local audit log of events, including redacted query heads, is kept for 90 days (akasha housekeeping prunes it).
Development
uv run pytest -q
uv run --python 3.11 pytest -qLicense
MIT
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
Hosted MCP memory for coding agents: persistent across sessions, editable markdown, team sharing.
Shared memory for coding agents. Stop re-explaining your codebase every session.
A second brain for your AI agent. Shared memory for your team's AI agents, plus public and private knowledge bases — works with ChatGPT, Claude, Cursor and any MCP client.
One memory, every AI. A shared, user-owned markdown memory your AI clients read and write over MCP.
Related MCP Servers
- AlicenseNot gradedqualityBmaintenanceProvides local-first, project-aware durable memory for coding agents, with a human-reviewed Markdown vault, MCP daemon, and dashboard for managing and retrieving shared knowledge.56 PyPI15MIT
- AlicenseNot gradedqualityDmaintenanceProvides persistent, local-first memory for coding agents with Markdown as the source of truth, exposed via CLI, loopback API, MCP, and Codex hooks for context retrieval and durable writes.MIT
- AlicenseNot gradedqualityBmaintenanceA local markdown memory and cross-agent context engine for AI coding assistants. It provides an MCP server with tools to search, add, retrieve, and distill persistent memory across tools like Claude Code, Cursor, and Zed.5MIT
- AlicenseAqualityBmaintenanceEnables coding agents to store, search, and retrieve long-term memory as plain Markdown files with a disposable SQLite index, including note management, decision/bug tracking, and codebase symbol lookup via MCP.8MIT