Encephalon CLI
Encephalon stores project decisions and conventions as JSON inside Git so coding agents can search them between tasks.
- 101 ★ on the repository
- Last commit
Minimal access
Why this level
- `init` adds blocks to `AGENTS.md` and `CLAUDE.md` and creates record files.
- Whatever the agent records travels with the Git commit, so keep secrets out of it.
Install
- Works in
In your terminal, with SkillFoxx CLI
npx skillfoxx add cli/encephalonDetects the agents on your machine, shows the access level and pins the version.
Other ways to install
Access and checks
How we reviewMinimal accessThe tool runs nothing and makes no network calls.
- `init` adds blocks to `AGENTS.md` and `CLAUDE.md` and creates record files.
- Whatever the agent records travels with the Git commit, so keep secrets out of it.
This is third-party code. Review the repository files before installing.
What it does
Encephalon is repository-local memory for agents. Small JSON records (decisions, architecture, conventions, workflows, incidents) live in Git next to the code, and a disposable SQLite index makes them searchable through a CLI and a synchronous JavaScript API. `init` creates up to three baseline records, prepares the cache and adds reversible blocks to `AGENTS.md` and `CLAUDE.md` that point the agent to the installed skill. Records are append-only: changed knowledge becomes a new record with `--supersedes`. There are no accounts, services, telemetry, embeddings, background daemon or runtime network access.
Who it is for. Developers whose agents forget decisions between sessions and keep re-learning why the project does things a certain way.
Good fit when
- The team makes an architecture decision and future agents need its rationale.
- An agent searches earlier conventions before editing an unfamiliar module.
- Several agents and people work in different branches and merge knowledge through Git.
- You want project memory without a cloud service or embeddings.
Not a fit when
- You need semantic search by meaning: search here is literal and terms combine with AND.
- Records would have to hold secrets or personal data: the files travel with Git.
- You need memory shared across different repositories.
Example request
Search Encephalon for authentication records, show the active decision and add one that supersedes it if we move to short-lived tokens.Limitations
You need Node.js 24.22.1 or newer; install the package at the root of the Git repository, as workspace-local and ephemeral installs and Yarn Plug'n'Play are unsupported. A corpus holds at most 1000 records and 8 MiB of JSON, with up to 1 MiB per record. Search returns 20 results by default, with a limit of up to 1000. Records are immutable: a correction is a new record. Parallel branches can create divergent heads, so CI can run `validate --allow-divergent-heads`.
How to disable. Run `npx --no-install encephalon init --remove`: it removes only the managed blocks from `AGENTS.md` and `CLAUDE.md`. Records, artifacts and the package stay, so delete them from the repository yourself.
FAQ
Where are records stored?
In the `encephalon/` directory of the Git repository: one JSON file per record plus immutable files under `_artifacts/`. The cache lives in `node_modules/.cache/encephalon/` and stays out of Git.
How do I replace an outdated decision?
Add a record with the same `kind` and `subject` and `--supersedes <id>`. It must supersede every active head with that kind and subject.
Does it run Git commands?
No, Encephalon never runs Git for you. You commit records and instruction changes yourself.
What should I do after merging branches?
Run `npx --no-install encephalon validate`. If several active heads conflict, add a record that supersedes them all.
Which record kinds are recommended?
`decision`, `architecture`, `convention`, `workflow`, `incident` and `context`.
Discussion
No questions or reviews yet.
Related
CLI toolsShared team memory for people and AI agents in Git: decisions and handoffs live in Markdown, reachable from Claude Code and Codex.
Shared long-term agent memory: notes in plain markdown files, with a MEMORY.md index loaded at the start of every session.
Engram by Gentleman Programming
Engram (Gentleman Programming)
Persistent memory for AI coding agents in a single Go binary: an MCP server on SQLite with full-text search that remembers your project across sessions
Engraphis keeps a coding agent's memory in a local SQLite database and returns an answer with its source, or abstains honestly.
Persistent agent memory in a folder of linked markdown notes, so Claude Code remembers a project across sessions
Local project memory for AI agents: repository, sessions and decisions in SQLite with evidence labels, no cloud, no telemetry.
Comparison with similar tools
Cards that share the main search query, and how they differ.
| Tool | Official | Authentication | Repository stars | Main difference |
|---|---|---|---|---|
| Encephalon (this card) | no | 101 | ||
| Basic Memory | no | not required | 4,557 | keeps notes as Markdown and connects over MCP; Encephalon holds immutable JSON records in Git and works through a CLI and a skill |
| agent-memory | no | 4,315 | standalone agent memory; Encephalon is bound to the repository and merges with Git branches |
README in short
Install as a dev dependency, then run `init` at the repository root. After that use `add`, `search --compact`, `show`, `list` and `gather`. Integrity is checked with `validate`.