EverCore Memory Tools

繁體中文

MCP server for using a self-hosted EverCore-compatible memory service with coding agents.

It gives agents durable project memory across sessions: decisions, conventions, bug fixes, roadmap context, repo-scoped recall, and Codex session summaries.

Requirements

• Node.js 20+
• A running EverCore-compatible API service

export EVERCORE_BASE_URL="http://localhost:1995"
export EVERCORE_DEFAULT_USER_ID="developer"

Set EVERCORE_API_KEY only when your EverCore endpoint requires bearer authentication.

MCP Setup

Use the package through npx:

{
	"mcpServers": {
		"evercore-memory": {
			"command": "npx",
			"args": ["-y", "@zwei-c/evercore-memory-tools"],
			"env": {
				"EVERCORE_BASE_URL": "http://localhost:1995",
				"EVERCORE_DEFAULT_USER_ID": "developer"
			}
		}
	}
}

For a local checkout:

{
	"mcpServers": {
		"evercore-memory": {
			"command": "node",
			"args": ["/path/to/evercore-memory-tools/bin/evercore-memory-mcp.mjs"],
			"env": {
				"EVERCORE_BASE_URL": "http://localhost:1995",
				"EVERCORE_DEFAULT_USER_ID": "developer"
			}
		}
	}
}

Tools

Daily workflow tools:

• evercore_scope - resolve the current repository memory scope
• evercore_briefing - render a Markdown context briefing
• evercore_remember - store durable project, user, or agent memory with safety checks
• evercore_recall - retrieve normalized memory snippets
• evercore_forget - delete an explicit memory or confirmed test scope
• evercore_ingest_codex - build or write a Codex rollout summary; dry-run by default
• evercore_list_spaces - list current/configured memory spaces
• evercore_fetch_history - fetch limited scoped memory history
• evercore_ingest_status - check whether a Codex transcript source hash is present
• evercore_request_status - infer limited request/source status from search evidence

Low-level compatibility tools:

• evercore_health
• evercore_search
• evercore_add
• evercore_flush
• evercore_delete

CLI

The same workflow is available from npm scripts when running from a checkout:

npm run scope
npm run briefing
npm run spaces
npm run history -- --scope project --memory-types raw_message,episodic_memory --query "recent decisions"
npm run ingest:codex -- --latest --dry-run
npm run ingest:status -- --latest

ingest:codex reads Codex rollout transcripts from ~/.codex/sessions/**/rollout-*.jsonl, summarizes useful session context, redacts common secret patterns, and can write project/agent memory to EverCore.

Project Isolation

Project memory is scoped through EverCore group_id. By default, the tool derives a stable group from the current Git remote, for example:

coding:github:example-org/example-repo

You can override or supplement scope with environment variables:

export EVERCORE_DEFAULT_GROUP_ID="coding:my-project"
export EVERCORE_DEFAULT_SESSION_ID="my-project"

Safety

The high-level write paths include a conservative sensitive-content guard for common secrets such as API keys, bearer tokens, passwords, cookies, private keys, and .env dumps.

Treat memory as durable operational context. Store decisions, conventions, verified fixes, and stable preferences; avoid storing raw secrets or transient logs.

Suggested Agent Prompts

Add the following to your agent's instructions file (e.g., AGENTS.md, copilot-instructions.md, or workspace guidelines) to make the agent proactively use EverCore memory:

## EverCore Memory

This workspace uses a self-hosted EverCore memory backend for durable cross-session context. The EverCore MCP tools (`evercore_*`) are available in every conversation.

### Session Start

- At the beginning of each conversation, call `evercore_briefing` to get a session-start memory briefing for the current repo scope.
- If no briefing tool is available, use `evercore_recall` with `scope: "project"` to check for prior decisions, preferences, or conventions relevant to the current repo.

### During Conversation

- Before making assumptions about user preferences, project conventions, or past decisions, search memory with `evercore_recall`.
- Treat retrieved memory as helpful context, not as proof. If memory conflicts with live files or services, prefer the live source and note the discrepancy.

### After Useful Interactions

Write memory with `evercore_remember` when the information is durable and likely useful later:

- User preferences or standing instructions
- Stable project decisions or architectural choices
- Verified service endpoints, operational facts, or configuration values
- Debug findings that explain a root cause
- Reusable commands or workflows

Do NOT store: transient output, speculative analysis, or low-value conversation filler.

### Privacy

Never store secrets: `.env` values, API keys, tokens, passwords, private keys, or personal identifiers. Summarize only the safe durable fact when sensitive context is involved.

Compatibility Notes

EverCore-compatible runtimes may expose different group listing behavior. If remote group listing is unavailable, evercore_list_spaces still returns current/config-derived spaces and reports the limitation in the response.

Raw message history uses search fallback because some EverCore runtimes only support extracted memory types through /api/v1/memories/get.

Maintainer Checks

npm run test
npm run tools
npm pack --dry-run

Networked smoke tests require an explicit EverCore endpoint:

EVERCORE_BASE_URL="http://localhost:1995" npm run smoke
EVERCORE_BASE_URL="http://localhost:1995" npm run high-level-tools