agent-julia MCP server
Commit Nov 2, 2026Provides a persistent persona and local-first markdown memory that synchronizes across Claude Code, Claude Desktop, and the Claude mobile app.
Also known as elninopl/agent-julia
- Stars
- 7
- Tools
- —
- Downloads, 30 days
- —
- Latest version
- —
- Last commit
- Nov 2, 2026
- License
- MIT
What is agent-julia MCP?
agent-julia provides a persistent persona and local-first markdown memory that synchronizes across Claude Code, Claude Desktop, and the Claude mobile app.
Summary generated from the project's README
About agent-julia MCP server
Agent Julia provides a persistent AI persona and a local-first markdown memory system that stays consistent across Claude Code, Claude Desktop, the Claude mobile app, and claude.ai. Instead of re-teaching preferences every time you switch devices, you define a single identity including name, language, and writing style. This persona remains active across all platforms by reading from a centralized git repository of plain markdown files that you own and control.
The system manages context efficiently by keeping a compact persona core of approximately 1,200 tokens in the active window while storing the rest of your knowledge in a searchable memory. It uses a SQLite index with keyword search and optional multilingual vector embeddings to retrieve relevant information only when needed. Users can set strict privacy rules to ensure specific data like passwords or keys are never stored. Setup is handled via a wizard using npx, which configures the necessary connections for your specific Claude environment.
What you can do with it
- 1Synchronize persona across devicesMaintain a consistent writing style and language preference when moving from Claude Code on a computer to the Claude mobile app.
- 2Store long-term project decisionsInstruct the agent to remember specific technical changes or project updates so they can be recalled in future sessions.
- 3Refine AI communication styleGive direct commands to change how the agent speaks, such as removing specific introductory phrases or changing the tone.
- 4Facilitate structured decision makingUse the built-in brainstorm skill to move from a vague idea to a documented recommendation using strategic thinking lenses.
Written from the project's README. Every use case is checked against a quote from it.
Automated checks
Ran Nov 15, 2026Full report →Not verified yet. A server needs a score of 80, no serious finding, and enough data for us to check. How checks work · What to fix for more points
- Source repository linked and reachableelninopl/agent-julia is public and reachablegithub.com/elninopl/agent-julia ↗Pass
- Package names this repository as its sourceNot checked
- Build provenance (Sigstore attestation)Not checked
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-11-02github.com/elninopl/agent-julia ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNot checked
- No critical advisory in the package or its dependenciesNot checked
- No hidden instructions to the model0 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNot checked
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubAgent Julia
One AI that knows you, in every Claude you use.
You build the persona once: what it is called, which language it answers in, how it writes and what it must never store. From then on you talk to it by name in Claude Code, Claude Desktop, claude.ai, the Claude app on your phone and on your other computers, and it is the same one everywhere. It remembers what you decided and writes the way you taught it. Everything it knows is plain markdown in a git repo you own.
npx agent-julia init
What it looks like
The phone and claude.ai reach your memory through server mode.
Why it helps
You keep re-teaching the same preferences. You told Claude Code to skip the "Great question!" preamble and to answer in Polish. Tomorrow, in Claude Desktop, the preamble is back and the answer comes in English. With Agent Julia you say it once, and every app reads the same correction from the next turn on.
Your CLAUDE.md has grown to 500 lines. All of it loads on every turn of every session, and the answers get worse as the window fills with things the task at hand does not need. Agent Julia keeps a persona core of about 1,200 tokens in context and leaves the rest in memory, where the agent finds the one page it needs when you ask.
Where it works
| How it connects | |
|---|---|
| Claude Code | registered by the wizard; the persona is in every session from the first message |
| Claude Desktop (Cowork) | registered by the wizard; you paste one short block into its settings once |
| claude.ai | a custom connector to your server, approved with your own password |
| The Claude app on your phone | the same connector: add it on the web and it is there |
| Your other computers | agent-julia init, then "On an agent-julia server" |
| A team or a household | a shared store mounted next to your own memory |
| Codex, Gemini CLI | the persona exported into their instruction file and kept current |
Highlights
- A persona you call by name. The wizard asks what it is called, then its pronouns, its language and how it writes. You open with "Julia, look at this" as you would with a colleague, and Julia is the one who answers.
- A voice you shape by talking. "Stop hedging." "Don't open with my name." Say it once, in passing, and it holds in every app. Take it back the same way.
- It catches what you forget to save. Ask it to remember and it does. With capture hooks on, a background pass after a Claude Code session also saves the decisions and corrections nobody asked it to keep.
- Yours, in plain files. Markdown in a git repo you control: open it, edit it by hand,
git logit, take it elsewhere. The search index is built from those files and rebuilds itself if you delete it. - Light on context. About 1,200 tokens of persona ride each turn. Everything else waits in memory until a question needs it.
- Search that gets your meaning. Keyword search with stemming and accent folding is always on. Add the optional multilingual model, which runs on your machine, and a question in Polish finds a note you wrote in English.
- Private where it counts. You decide what it must never store, starting from passwords, keys, card numbers and other people's private details, and that rule rides every message. The server listens only on your own machine until you turn on authentication, and claude.ai gets in only after you type the owner password.
Install
npx agent-julia init
Requires Node.js 24+ (it uses the built-in node:sqlite — no native module to compile or rebuild). There's no separate install step: npx fetches agent-julia into its own cache and runs the wizard in one go, and the MCP server launches the same way (npx -y agent-julia@latest serve), so it stays current. Prefer it installed permanently? npm i -g agent-julia.
Choosing the local model for search changes how the server is launched. npx runs from a cache that cannot load the optional model package, so the wizard registers an installed copy instead (npm i -g agent-julia @huggingface/transformers), after checking that it can load the model. Node is registered by a path that survives upgrades: on Homebrew that is opt/node, not the versioned Cellar directory the next brew upgrade deletes. If the registered program ever disappears, agent-julia doctor says so.
The wizard starts with the name you will be calling it by, then pronouns, language, and voice; where your memory lives and whether to version it with git; search; and which Claude apps to register. It either writes a small persona block into each app's startup context — backed up first, inside a marked block, fully reversible — or prints the exact changes for you to make by hand (see Manual setup).
When you're done, restart your Claude apps so they pick up the new MCP server.
Usage
You don't call tools or memorize commands. You talk to your agent by name, and it reaches into memory on its own. A few natural examples:
Save something (→ ingest)
- "Remember that we dropped Redis — we're on Postgres LISTEN/NOTIFY now."
- "Note for the Atlas project: the weekly review moved to Mondays."
- The agent also tries to capture durable facts on its own — but treat that as a bonus, not a guarantee (see the note below). Saying "remember: …" is the reliable channel.
On automatic capture. agent-julia is an MCP server, which is pull-only: it never writes on its own, only when the model calls a tool. So "save this" happens only if the agent decides to call
ingestmid-conversation — reliable when you ask explicitly ("remember: …"), best-effort when left to the agent's judgment, and easy to miss during a focused task. The persona core nudges it to capture and to say what it saved, so a miss is visible. If something important didn't land, just say "remember: …".
Recall (→ search, read)
- "What did we decide about auth?"
- "What do you know about the Atlas pricing model?"
- "Did I say anything about onboarding last week?"
Steer the voice (→ correct_voice)
- "Stop hedging — commit to an answer."
- "Don't open every reply with my name."
- The correction is recorded and applied from the next turn, on every surface.
Browse (→ list)
- "What's in my memory?" · "List every page you have."
Think something through (→ the brainstorm skill)
- "Help me decide whether to take the Berlin offer."
- "Let's brainstorm the pricing for the new plan."
- "Back to the office-move question from last week." — sessions are resumable; the state lives in memory, so you can start on one machine and finish on another.
Everything you save lands as markdown in your repo and is committed, so you can open it, edit it by hand, or git log the history any time.
How it works
- Canonical store — plain markdown in a git repo. Human-readable, portable, versioned, private. This is the source of truth, not a database.
- Derived index — SQLite (FTS5 full-text + optional vector embeddings) built from the markdown, via Node's built-in
node:sqlite(no native module to compile). It's disposable: delete it and it rebuilds itself from your files. - Budgeted core — a compact persona block is injected into Claude Code's
CLAUDE.mdand Claude Desktop's global instructions. It stays within a token budget you set, so it never crowds out the conversation. Each layer is budgeted separately, and the part that yields is ours: identity and the privacy rail come off the top, your voice and your corrections each get a share, and the shipped universal rules take what's left.maintenanceanddoctorboth say when something didn't fit, rather than trimming in silence. - A server per session, one memory — every Claude Code and Claude Desktop session starts its own
agent-juliaserver over stdio, and all of them read and write the same store and index, so they share one memory and one persona. Writes from different sessions take turns under a lock, startup chores that one server can do for all of them (maintenance, refreshing installed files, re-embedding after a model change) are done by whichever starts first, and a server exits when its session does. The local embedding model runs in a separate process that exits after a minute without use, so an idle server holds about 40-50 MB.
Skills
agent-julia ships one skill, installed into ~/.claude/skills/ (which both Claude Code and Cowork read) by the wizard and refreshed automatically every time the server starts — so existing installs pick it up on their next session, no manual step:
brainstorm — a structured facilitator that takes a fuzzy idea or an open decision to a committed outcome. Built for business and life questions, not code. What makes it different from just chatting:
- A real process — frame (question, criteria, constraints) → diverge → challenge (assumptions, pre-mortem, inversion) → converge on a recommendation you confirm section by section.
- One question per message, with answer options — a dialogue, not a questionnaire.
- Thinking lenses — distillations of proven tools (strategy kernel, jobs-to-be-done, willingness to pay, fear-setting, inversion, regret minimization, one-way vs two-way doors…), picked to fit the topic and named when used.
- Deep mode — for high-stakes calls the agent offers a panel of 3–4 adversarial perspectives (skeptic, the other side, operator…) run as parallel subagents where available. It costs real tokens, so it never runs without your yes.
- It remembers — session state is saved to memory after every phase, so a brainstorm survives days and devices ("back to the X question"); the outcome lands as a decision doc with the options you killed and why, so nothing gets relitigated.
- Your places, not hardcoded ones — at the end it offers the doc as a Markdown/HTML file and, based on what tools you have connected, proposes where the actions should go.
The skill starts only when you ask for it (or accept a one-line offer). Your own skill under the same name is never overwritten: installs and uninstalls only touch copies carrying the author: agent-julia marker.
Capture hooks
The agent saves what it is told to save and, on a good day, what it notices. Both slip in a long session. agent-julia hooks install adds three Claude Code hooks that catch what slips, without touching any hook of yours:
- On every prompt (
UserPromptSubmit): when your message reads like a correction of the voice ("don't say", "nie pisz", "sounds off", "zamiast"), a one-line reminder to callcorrect_voicebefore replying. EverynudgeEveryTurnsturns (10 by default), a one-line reminder toingestwhat the session decided. - Before a compaction and at the end of a session (
PreCompact,SessionEnd): a backgroundclaude -preads what was said since the last pass, searches the memory, and saves the durable facts and voice corrections the session left out. It can only search, read,ingestandcorrect_voice, runs with hooks off, gives up after five minutes, and never holds up your session. What it did goes tohooks.lognext to the config.
agent-julia hooks install # or: uninstall, status
"capture": { "hooks": true, "nudgeEveryTurns": 10, "extractOnCompact": true }
- The hooks go into
settings.jsonof the Claude Code account in use ($CLAUDE_CONFIG_DIR, else~/.claude), with a one-time backup. They run a small script next to the config with Node directly, so a prompt costs one Node start and no package download; the server keeps the script current with each update. - The background pass runs
claude -pon your Claude plan, with Sonnet. Anthropic has changed howclaude -pusage counts against plans before and may again; setextractOnCompacttofalseto keep only the reminders. - It works the same on a machine connected to a server: the pass saves through the relay.
Claude.ai, the mobile app and Claude Desktop run no hooks. For them, "serverNudge": true in capture has the server itself ask: when a session has kept reading for 20 minutes and saved nothing, the next search, read or list result carries one extra line asking whether something is worth keeping. Once per 20 minutes at most, and never inside the result itself, which stays as it was. Off by default.
Beyond Claude
The persona you built is not locked to Claude. agent-julia export codex writes it into ~/.codex/AGENTS.md, export gemini into ~/.gemini/GEMINI.md, and export <path> into any AGENTS.md-style instruction file — as a marked, removable block, backed up on first touch, and kept refreshed by the server on every boot (a voice correction you make in Claude reaches Codex on its next session). The export carries the persona itself — identity, voice, corrections, privacy rail — without the Claude-specific memory instructions; attach the same MCP server in the other tool if it supports MCP, and the memory follows too.
Run as a server
By default every Claude session starts its own Agent Julia over stdio, on the machine the session runs on. agent-julia serve --http runs one long-lived process instead, serving every session of every client over MCP's Streamable HTTP transport at /mcp. It is the way to reach one memory from more than one machine, and the only way to reach it from a client that cannot start local processes.
"server": { "host": "127.0.0.1", "port": 8787, "auth": "none", "maintenanceEveryMinutes": 60 }
- One process, one index per store, many sessions. Writes from different sessions are ordered by the same store lock the stdio servers use, so a CLI command on the same machine is still safe to run.
- It pulls and maintains every store on start and then every
maintenanceEveryMinutes. It never touches~/.claude, skills, exports or Claude Code's memory on the machine it runs on: there is no local Claude there to serve. GET /healthzreturns JSON for a monitor: version, open sessions, and per store the last write, the last maintenance and its outcome, and how many commits are waiting to be pushed.- It binds loopback by default and refuses to start without authentication on any other address, or with a
publicUrlset. Requests must carry a Host the server answers to, and withauth: "none"a request that came through a proxy is refused. --hostand--portoverride the config for one run. Each persona is its own process with its own config (AGENT_JULIA_CONFIG).
Tokens ("auth": "bearer") are for machine clients: a remote proxy, a monitor, a bot.
agent-julia server token add laptop # prints the token once
agent-julia server token add group --stores team # this one reaches only the store "team"
agent-julia server token list
agent-julia server token revoke laptop
Clients send Authorization: Bearer <token>. Tokens are kept as SHA-256 hashes in secrets/tokens.json next to the config, readable by its owner only, and a running server picks up an added or revoked token without a restart. A token with --stores sees only those stores (primary is your own): the others are absent from search, list and read, it writes only with store, and it cannot change the voice. It still reads the voice: get_core gives it the persona and your corrections, so a group-chat process speaks as your persona over a shared memory. Don't hand such a token to anyone who should not see your corrections. A session belongs to the token that opened it. Without a token, /healthz answers only whether the server is up and its version; with one, it lists the stores that token reaches.
Claude.ai and the Claude mobile app ("auth": "oauth") connect as a custom connector, over OAuth. Claude.ai reaches the server from Anthropic's cloud, so it has to be reachable from the internet over HTTPS: put a reverse proxy or tunnel on the same machine in front of it (Caddy, nginx, cloudflared) and give its address as publicUrl.
"server": { "auth": "oauth", "publicUrl": "https://julia.example.com" }
agent-julia server set-owner # the password that approves a connection
agent-julia serve --http
Then in claude.ai: Settings → Connectors → Add custom connector, URL https://julia.example.com/mcp. Claude registers itself and opens the server's consent page, which names the app asking and where it will be sent back; type the owner password and allow. A connector added on the web is in the mobile app too. On a Team or Enterprise plan every member who connects goes through the same page, so they all need the owner password: this mode is for a server one person uses.
- Access tokens last an hour and are refreshed without asking; a refresh token is replaced on every use and lapses after 90 days without one. Tokens are kept as hashes in
secrets/oauth.json, readable by its owner only, so a restart logs nobody out. agent-julia server oauth listshows the connected apps;server oauth revoke <client-id>(orall) cuts one off at once, running server included. Changing the owner password does not disconnect anyone by itself.- After ten wrong passwords within 15 minutes the consent page stops accepting any until the window passes.
- Bearer tokens keep working next to OAuth, for the clients that are not Claude.
Another machine connects to the server instead of keeping its own memory. Make a token for it on the server, then run agent-julia init on the other machine and choose "On an agent-julia server": it asks for the address and the token, checks both, and registers the server with that machine's Claude apps. The config it writes names the server:
"remote": { "url": "https://julia.example.com/mcp", "tokenEnv": "AGENT_JULIA_TOKEN" }
agent-julia serveon that machine is then a relay: stdio towards Claude, HTTP towards the server. Tools, theagent-julia://coreresource and the instructions come from the server unchanged. No store, index or git runs there, and the commands that work on a store say to run them on the server.- At each session start it refreshes the persona block in
~/.claude/CLAUDE.mdand the shipped skills from the server's core, and again aftercorrect_voice, as a local install does. - The token is read from the variable named in
tokenEnv, else fromsecrets/remote-tokennext to the config, where the wizard keeps it (readable by you only). It is never written to the config. - When the server is down, a session still starts within seconds: it gets the tools it saw last, and each call answers with an error naming the server instead of hanging. The relay tries again every 30 seconds and picks up a restarted server by itself.
agent-julia doctorchecks the way to the server: that it answers, that it takes the token, and whether its version matches this machine's.serve --remote <url>points one run at another server.
Reference
Deeper detail — search, persona, the file layout, and the full configuration and command reference.
Search
Two layers work together, and both run locally.
Keyword (always on). SQLite FTS5 with Porter stemming, so debug matches debugging, and diacritics folding, so cafe matches café and lodz matches Łódź (the letters SQLite cannot fold on its own — ł, đ, ø, ß — are carried by a folded shadow column, so titles and snippets keep their real spelling). For languages without spaces between words — Chinese, Japanese, Korean, Thai — Agent Julia switches to a trigram tokenizer, with a substring fallback for the one- and two-character queries that are ordinary in those languages. A question asked as a sentence is answered by a ladder: all terms, then content words only, then any two, then the most distinctive one alone. Each hit says which rung it came from, so a loose answer looks loose.
Meaning (optional). Turn on semantic search to find a note even when you phrase it differently, and across languages — a question in Polish can surface an English note. You choose how it runs:
- Local model — a multilingual model (the
multilingual-e5family, ~118 languages) runs on your machine, in a separate process that starts when a search or a write needs it and exits after a minute without use. The memory the model takes goes back to the system then, instead of staying with every open Claude session. The first search after a quiet minute takes under a second longer while the model loads; the ones after it take milliseconds. Pages are embedded in parts, split on their own headings, so a long page is searchable to its end and not just to the model's first 512 tokens. No server, no API key, fully offline after a one-time model download. Pick a size in the wizard: small (~120 MB download, ~0.8 GB RAM while running), base (~280 MB, ~1.1 GB), or large (~560 MB, ~1.7 GB). The models run at 8-bit precision (q8): on the maintainer's store it ranked the same top page as full precision for 27 of 28 queries, at a third of the memory. Setembedding.dtypetofp32if you want full precision anyway. The wizard reads your machine's RAM and CPU cores and suggests a tier. RAM is rarely the limit, so the suggestion leans on cores, since a bigger model's main cost is slower CPU inference per query. Needs one extra package,@huggingface/transformers, which stays optional so the base install is tiny. - Hosted API — any OpenAI-compatible endpoint (OpenAI, or a local server like Ollama or LM Studio). Your key is read from an environment variable and never written to disk.
- None — stay keyword-only. The default, and completely dependency-free.
Hybrid mode blends keyword and meaning, and degrades gracefully: with no embeddings configured, it's simply keyword search.
agent-julia MCP questions
Where is my data stored?
Everything is stored as plain markdown files in a git repository that you own and control.
How does it work with different Claude applications?
It works with Claude Code, Claude Desktop, claude.ai, and the Claude mobile app by using a shared persona and memory.
Can I edit the memory manually?
Yes, since the memory is stored in plain markdown within a git repo, you can open and edit it by hand or use git to view history.
Does it use a lot of context window?
No, it keeps a compact persona core of about 1,200 tokens in context and leaves the rest in memory to be retrieved as needed.