The package is designed as a localhost-first memory stack. This now matches both the documentation and the shipped Compose defaults:
- published ports bind to
127.0.0.1by default; - remote exposure must be an explicit, deliberate choice.
Do not commit to the repo:
OPENAI_API_KEYGOOGLE_API_KEYNEO4J_PASSWORD- bearer tokens for remote MCP
- local
.envfiles
Repo surfaces should contain shared config and env expansion, not the secrets themselves.
The canonical runtime env file lives outside the repo: ~/.claude/graphiti.neo4j.env (or graphiti.falkordb.env), chmod 600. Shipped Docker Compose stacks load it via ${HOME}/.claude/graphiti.<backend>.env with required: false, so the stack comes up even without the file (using env defaults), and real secrets never land in the repo working tree.
graphiti-memory lives in the repo .mcp.json.
That means Claude Code applies model approval for project-scoped MCP servers.
Do not cheat this model by moving sensitive config into shared files without reason.
templates/project/.mcp.graphiti.fragment.json
This is a simple localhost HTTP template. It is a good fit for a local Graphiti stack on the same machine.
For the remote path you must add auth via .mcp.json:
headers- or
headersHelper
Minimal examples are in:
ops/examples/mcp.graphiti.remote-bearer.example.jsonops/examples/mcp.graphiti.remote-headers-helper.example.json
ops/caddy/graphiti.Caddyfile is a local reverse-proxy example without auth.
Do not treat it as a production-ready remote exposure config.
It holds:
- summaries of past sessions
- queued payloads
- dead-letter records
- runtime stamp
- logs
Therefore:
- do not commit this tree
- do not sync it via git as shared team memory
- do not expose it to Claude as a regular knowledge corpus without an access policy
In the repo .claude/settings.json you can add a deny policy such as:
{
"permissions": {
"deny": [
"Read(./.claude/state/**)",
"Read(./.env)",
"Read(./.env.*)",
"Read(./secrets/**)"
]
}
}Then the following are mandatory:
- auth
- network-level access restriction
- separate password for Neo4j
- separate token for the MCP proxy
- verification that no MCP registration contains a hardcoded secret — project
.mcp.json, user-scope entries in~/.claude.json, or plugin-supplied servers. URL-embedded keys (e.g.?apiKey=...) count as hardcoded for this rule.
Shared repo config is fine.
Shared .claude/state/ across multiple people via git is not.
For a team, split:
- shared repo config
- local operator state
- remote Graphiti backend