Skip to main content
Glama
FreshMemory MCP

FreshMemory MCP

by sarthakshah

FreshMemory MCP

AI memory that checks whether it is still true.

CI

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 demo

The 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 start

To install the command locally:

npm install -g .
fresh-memory-mcp --version

Register 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-mcp

The 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

  1. Store a durable memory with remember.

  2. Link it to a local file with track_source.

  3. Run sync_sources, or keep fresh-memory-mcp watch running.

  4. Exact JSON changes automatically create a replacement memory in auto mode.

  5. Text and review-mode changes appear in review_changes.

  6. Accept or dismiss a pending change with resolve_source_change.

  7. Use watch_status to 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 10

The 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

remember

Store durable information with freshness metadata

recall

Search current memory and report relevant warnings

supersede

Replace a memory while preserving history

invalidate

Mark a memory unusable without deleting it

audit_memory

Find expired, conflicted, or reviewable memories

explain_memory

Show state, history, dependencies, dependents, and tracked sources

track_source

Link an active memory to a local JSON or text file

sync_sources

Check tracked sources and apply safe changes

review_changes

List source changes waiting for review

resolve_source_change

Accept or dismiss a pending source change

watch_status

Report source health, errors, overdue checks, and pending changes

Safety model

Situation

Behavior

Exact JSON value changed in auto mode

Supersede the old memory automatically

JSON value changed in review mode

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.

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, or observation

  • statement: human-readable information

  • key: stable identifier used for conflict detection

  • scope: project, client, or domain boundary

  • source: where the information came from

  • confidence: value from 0 to 1

  • valid_from, review_after, and expires_at

  • depends_on: memory IDs supporting this memory

  • tags and 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 tools
audit_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

    B3.2/5.0

    Scored across 11 tools

    Disambiguation4/5

    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.

    Naming Consistency4/5

    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.

    Tool Count5/5

    11 tools is well-scoped for a memory freshness and source-tracking server; each tool covers a distinct lifecycle stage without obvious redundancy.

    Completeness3/5

    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

    ActivityStale
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables 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
    • A
      license
      Not graded
      quality
      B
      maintenance
      Gives 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 npm
      3
      Apache 2.0
    • A
      license
      A
      quality
      B
      maintenance
      Enables 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.
      11
      AGPL 3.0
    • A
      license
      Not graded
      quality
      A
      maintenance
      Enables 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 npm
      159
      MIT