Step-by-step guide
Connect the memory system you trust
Keep the agent’s memory experience while choosing where organizational knowledge lives.
What this changes
Some teams want repository-readable memory; others already have a knowledge system of record. Clarvis keeps the agent-facing behavior stable while the storage choice remains yours.
-
01
Ownership of knowledge
Durable context can live inside the governance and retention model your team already uses.
-
02
A stable agent experience
Roles keep working with memory even when its storage changes.
-
03
A reversible decision
The storage system does not have to become the architecture of every agent.
Minimum setup
Start with one working configuration.
Start with fixed files before writing a service. This smallest provider makes existing, reviewed documents available at run start and exposes no memory write path.
{
"memory": {
"enabled": true,
"provider": {
"kind": "file",
"paths": ["docs/CONSTITUTION.md", "docs/CODING-STANDARDS.md"]
}
}
}Use a file provider when the repository already owns the documents. Move to MCP or an executable provider only when the source of truth lives elsewhere or needs custom governance. Note the scope: a provider of kind mcp, executable or plugin named by a repository's own .clarvis/settings.json, and any enabledPlugins or mcpServers entry it depends on, is withheld from the merge until you approve that workspace with /workspace-trust. Declare it in ~/.clarvis/settings.json to take effect immediately.
Working patterns
Adapt it to work you actually do.
Open a pattern to see the complete files and the reason behind each choice.
Pattern 01 A knowledge base your company already runs Configuration +
Declare this in your personal ~/.clarvis/settings.json, or run /workspace-trust after committing it: a repository's own mcpServers and enabledPlugins are withheld from the merge until that workspace is approved. The knowledge lives behind an internal API that a tool server already exposes, and it predates this agent, so its tools are called things like `kb_search`. You do not want a second copy of it in every checkout, and you want writes to go through the same API everything else uses.
{
"mcpServers": {
"acme-kb": { "command": "acme-kb-server", "args": ["--stdio"] }
},
"memory": {
"provider": {
"kind": "mcp",
"server": "acme-kb",
"tools": {
"list_memories": "kb_list",
"read_memory": "kb_get",
"grep_memories": "kb_grep",
"query_memories": "kb_search",
"write_memory": "kb_put",
"edit_memory": "kb_patch",
"delete_memory": "kb_delete"
},
"seed_tool": "kb_profile"
}
}
}Pattern 02 Selecting a provider a plugin offers Configuration +
Someone packaged a memory service as a plugin. You want to use it, and you want the fact that you chose it to be an explicit act rather than something the plugin arranged for itself.
{
"enabledPlugins": ["acme-memory"],
"memory": {
"enabled": true,
"provider": { "kind": "plugin", "plugin": "acme-memory" }
}
}Verify the behavior
Check the boundary, not just the happy path.
Use a small disposable task first. Confirm what works and what is deliberately unavailable before relying on the configuration in a real workflow.
- 01
The selected documents appear in the run’s opening memory context.
- 02
A read-only provider does not expose memory write, edit, or delete tools.
- 03
If a custom provider is unavailable, the run proceeds with no memory at all and is never quietly served from the built-in wiki instead. There is no on-screen warning for this today: to read the reason, run a host other than the terminal app with the log level at warn and look for memory_provider_unavailable.