FreshMemory MCP
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@FreshMemory MCP remember the campaign budget is $50,000 and track campaign.json"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
FreshMemory MCP
AI memory that checks whether it is still true.
FreshMemory is a local Model Context Protocol server that links important memories to their original sources. It detects source changes, preserves revision history, and flags decisions that relied on outdated information.
The problem
Most memory systems optimize recall. They can retrieve an old budget, a new budget, and a decision based on the old budget without explaining which one should still be trusted.
FreshMemory adds deterministic lifecycle rules:
Structured source changes can automatically replace outdated memories.
Unstructured document changes wait for review instead of being guessed.
Dependents of changed information require review.
Expired information is excluded by default.
Duplicate current keys are surfaced as conflicts.
History remains inspectable in a local SQLite database.
Related MCP server: al-buddy-memory-mcp
Requirements
Node.js 22.13 or newer
No API key
No hosted service
No runtime dependencies
Current version: 0.2.2 — GitHub-only public beta.
FreshMemory is distributed from GitHub for public testing. The local behavior is tested on Node.js 22.13 and 24. It has not been published to npm, and npm publishing remains intentionally blocked.
Use sample or non-sensitive data while evaluating the beta. See the testing guide for safe setup, practical scenarios, and feedback instructions.
Try the demo
npm run demoThe demo tracks a campaign budget in a JSON file. When the budget changes from $50,000 to $35,000, FreshMemory automatically supersedes the old memory and marks a paid-search allocation based on the old budget as needing review.
Run locally
npm test
npm startTo install the command locally:
npm install -g .
fresh-memory-mcp --versionRegister the installed command with Codex:
codex mcp add fresh-memory \
--env FRESH_MEMORY_DB=/absolute/path/to/fresh-memory.sqlite \
--env FRESH_MEMORY_SOURCE_ROOTS=/absolute/path/to/allowed/files \
-- fresh-memory-mcpThe default database location is platform-specific. Set FRESH_MEMORY_DB to use an explicit path.
Connect an assistant
Codex
[mcp_servers.fresh-memory]
command = "fresh-memory-mcp"
[mcp_servers.fresh-memory.env]
FRESH_MEMORY_DB = "/absolute/path/to/fresh-memory.sqlite"
FRESH_MEMORY_SOURCE_ROOTS = "/absolute/path/to/files:/another/allowed/path"Claude Desktop
{
"mcpServers": {
"fresh-memory": {
"command": "fresh-memory-mcp",
"env": {
"FRESH_MEMORY_DB": "/absolute/path/to/fresh-memory.sqlite",
"FRESH_MEMORY_SOURCE_ROOTS": "/absolute/path/to/files"
}
}
}
}FRESH_MEMORY_SOURCE_ROOTS is required only for track_source and source-sync features. Without it, FreshMemory can still store and recall memories, but it refuses to read any source file. Use : between allowed directories on macOS and Linux, and ; on Windows.
Automatic freshness workflow
Store a durable memory with
remember.Link it to a local file with
track_source.Run
sync_sources, or keepfresh-memory-mcp watchrunning.Exact JSON changes automatically create a replacement memory in
automode.Text and review-mode changes appear in
review_changes.Accept or dismiss a pending change with
resolve_source_change.Use
watch_statusto find errors, overdue checks, and pending changes.
Structured JSON example
Given this file:
{
"campaign": {
"budget": "$50,000"
}
}Track the memory using:
{
"memory_id": "MEMORY_ID",
"kind": "json_file",
"path": "/absolute/path/to/campaign.json",
"selector": "/campaign/budget",
"statement_template": "The campaign budget is {{value}}.",
"mode": "auto",
"interval_seconds": 300
}The selector is a JSON Pointer. Exact structured values are safe to render from the statement template without asking a model to interpret the document.
Text document example
Text files always use review mode. FreshMemory detects that the file changed but does not claim to understand the new policy. An assistant or person must review the document and provide the replacement statement.
Background commands
fresh-memory-mcp sync
fresh-memory-mcp status
fresh-memory-mcp changes
fresh-memory-mcp watch
fresh-memory-mcp watch --poll 10The watcher polls for sources whose individual interval_seconds has elapsed. It stays quiet when nothing changes and prints only meaningful changes or errors.
MCP tools
Tool | Purpose |
| Store durable information with freshness metadata |
| Search current memory and report relevant warnings |
| Replace a memory while preserving history |
| Mark a memory unusable without deleting it |
| Find expired, conflicted, or reviewable memories |
| Show state, history, dependencies, dependents, and tracked sources |
| Link an active memory to a local JSON or text file |
| Check tracked sources and apply safe changes |
| List source changes waiting for review |
| Accept or dismiss a pending source change |
| Report source health, errors, overdue checks, and pending changes |
Safety model
Situation | Behavior |
Exact JSON value changed in | Supersede the old memory automatically |
JSON value changed in | Create a pending change |
Text file changed | Create a pending change |
Source disappeared or became invalid | Report a source error; keep existing memory |
No source roots are configured | Refuse to read or track source files |
Source is outside configured roots | Reject it |
Two active memories share a key and scope | Mark both as conflicted |
FreshMemory never uses an LLM inside the server, never silently interprets prose, and never deletes history when a source changes.
Recommended agent behavior
Tell your assistant:
Store only durable, confirmed information. Link important facts to their original sources when possible. Sync tracked sources before relying on them. Automatically accept only exact structured changes. Review ambiguous changes and surface freshness warnings rather than guessing.
Memory model
Every memory can include:
type:fact,assumption,decision,preference,constraint, orobservationstatement: human-readable informationkey: stable identifier used for conflict detectionscope: project, client, or domain boundarysource: where the information came fromconfidence: value from0to1valid_from,review_after, andexpires_atdepends_on: memory IDs supporting this memorytagsand JSON metadata
Default review periods are 30 days for assumptions, 90 days for constraints, 180 days for facts and decisions, and 365 days for preferences. Observations do not receive a default review date. Pass review_after: null to disable the default.
Current limitations
Version 0.2 watches local JSON and text files only.
External APIs, databases, web pages, and SaaS connectors are not included yet.
JSON selectors use JSON Pointer rather than JSONPath.
Search is lexical rather than embedding-based.
Team synchronization and access controls are not included.
The assistant must call the MCP tools; FreshMemory cannot override untracked conversation context.
These constraints keep automatic updates local, explainable, safe, and easy to test.
Project documentation
License
FreshMemory is available under the MIT License.
Available Tools
11 toolsaudit_memoryC
List memories that are expired, superseded, invalidated, conflicted, or need review.
Inputs: limit, scope.
explain_memoryC
Explain a memory's state, history, dependencies, dependents, and replacement lineage.
Inputs: id (required).
invalidateB
Mark a memory invalid without deleting its history. Dependents will require review.
Inputs: id (required), reason.
recallB
Search memory. Returns only current, non-conflicted memories by default and reports relevant stale items as warnings.
Inputs: limit, query, scope, include_stale.
rememberC
Store a durable fact, assumption, decision, preference, constraint, or observation with freshness metadata.
Inputs: type (required), statement (required), key, tags, +8 more.
resolve_source_changeB
Accept or dismiss a pending source change. Text changes require a reviewed replacement statement when accepted.
Inputs: action (required), change_id (required), reason, statement.
review_changesC
List source changes waiting for human or agent review.
Inputs: limit, scope.
supersedeC
Replace a memory while preserving history. Dependents of the old memory will require review.
Inputs: old_id (required), statement (required), key, tags, +10 more.
sync_sourcesC
Check tracked local sources now. Structured auto-mode changes replace memory; review-mode changes become pending.
Inputs: due_only, source_id.
track_sourceC
Link an active memory to a local JSON or text file and establish its current value as the baseline.
Inputs: kind (required), path (required), memory_id (required), mode, +3 more.
watch_statusC
Show tracked source health, overdue checks, errors, and pending changes.
Inputs: scope.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 11 tools
Each tool targets a distinct memory or source lifecycle action, but audit_memory, review_changes, and watch_status all surface review/health information, which could cause minor misselection between listing problems versus listing pending changes.
Mostly snake_case verb_noun (track_source, sync_sources, review_changes), with a few bare verbs (remember, recall, supersede, invalidate) that deviate slightly but remain clear and consistent in style.
11 tools is well-scoped for a memory freshness and source-tracking server; each tool covers a distinct lifecycle stage without obvious redundancy.
Core memory create/read/update/invalidate and source sync are covered, but notable gaps exist: no tool to manage memory dependencies directly, no explicit conflict resolution for memories (audit lists conflicts but doesn't resolve), and no way to untrack a source.
Maintenance
Related MCP Connectors
Persistent memory for AI agents, for code, research and everyday life. Stale facts retire.
Shared memory for your AI agents. Every fact shows its source, and stale facts get replaced.
Persistent AI memory with semantic search, conflict detection, and ticketing.
Persistent memory for AI agents. Search and store durable facts, preferences and decisions.
Related MCP Servers
- AlicenseNot gradedqualityCmaintenanceEnables AI harnesses to maintain a persistent memory layer backed by a local SQLite file, providing MCP tools to add, search, deprecate, and synchronize facts without deleting history.MIT
- AlicenseNot gradedqualityBmaintenanceGives AI agents governed, provenance-tagged memory where facts are invalidated rather than deleted and every recall result carries validity dates, confidence, and replacement links. Stores memory in a local SQLite file with tools for remembering, recalling, invalidating, and pinning facts, plus policy enforcement and an audit trail.103 npm3Apache 2.0
- AlicenseAqualityBmaintenanceEnables AI coding agents to persist atomic, token-budgeted facts across sessions via SQLite-backed full-text search, automatically superseding outdated entries and flagging memories as stale when Git webhooks detect changes to anchored repo files.11AGPL 3.0
- AlicenseNot gradedqualityAmaintenanceEnables AI agents to maintain auditable, local-first long-term memory in a single SQLite file, preserving source evidence and retiring dependent memories when sources are corrected so Claude Code, Cursor, and Codex start from current recorded evidence.158 npm159MIT