Skip to main content
Glama
SAE4U Memory

SAE4U Memory

Official
by Simple4uhq

SAE4U Memory

A persistent memory architecture for Claude — MCP server + hooks + rules + prompts + templates. Free and open source. MIT.

Claude forgets you every time you close the chat. SAE4U Memory fixes that, and goes further: it ships an opinionated architecture for how persistent memory should be organized — not just storage, but classification, periodic review, persona, cleanup, and session continuity.

Built by Simple4u, an engineering firm in New York. Part of the SAE4U OSS family alongside sae4u-agent.


What you get

Core (works in any MCP client — Claude Desktop, Claude Code, etc.)

  • Two-corpus recall — recall(query) searches BOTH SQLite facts AND your markdown memory files (Claude Code auto-memory dirs + ~/.sae4u-memory/) in one call. No re-explaining yourself.

  • Hierarchical memory — remember(text, category) with 5 categories: user, feedback, project, reference, general.

  • Session journals — journal(text) for end-of-session notes written to ~/.sae4u-memory/journals/YYYY-MM-DD.md for human reading.

  • Customizable persona — persona.md shapes the AI's identity. Default: Simple, a peer-level coder friend who remembers things.

  • Local-first — your memory lives in ~/.sae4u-memory/ on your machine. Nothing leaves.

Architecture (Claude Code with --code-full)

  • hooks/memory-tick.sh — UserPromptSubmit hook that fires every 10 min and forces a brief memory review. Catches borderline observations before they fall out of context.

  • rules/ — 10 universal feedback rules covering memory discipline, session continuity, anti-confabulation, hardcode prevention, post-write review.

  • prompts/ — opinionated session-open and session-close prompts that pair with the architecture.

  • templates/ — formats for MEMORY.md, feedback rules, project facts, and tick logs.

  • commands/memory-distill.md — weekly distill ritual that promotes tick-log items to permanent memory interactively.


Related MCP server: Claude Memory Server

Install

Minimum (MCP only)

git clone https://github.com/Simple4uhq/sae4u-memory
cd sae4u-memory
pip install -e .
sae4u-memory init

This wires the MCP server into Claude Desktop and Claude Code, and appends a guidance block to ~/.claude/CLAUDE.md. Restart your client and the memory tools are live.

Full architecture (Claude Code only)

sae4u-memory init --code-full

Adds:

  • Copy hooks/memory-tick.sh → ~/.claude/hooks/memory-tick.sh

  • Register the hook in ~/.claude/settings.json under hooks.UserPromptSubmit

  • Scaffold ~/.sae4u-memory/MEMORY.md

  • Drop default rules into ~/.sae4u-memory/rules/

Restart Claude Code. The tick will fire every 10 min and instruct the AI to review and classify recent context.

Flags

sae4u-memory init --desktop        # Claude Desktop only
sae4u-memory init --code           # Claude Code MCP only
sae4u-memory init --code-full      # Claude Code MCP + hook + scaffold
sae4u-memory init --no-claude-md   # skip CLAUDE.md guidance block
sae4u-memory init --dry-run        # preview changes without applying
sae4u-memory uninstall             # remove all config entries

Tools exposed (MCP)

Tool

Purpose

remember(text, category)

Save a fact to long-term memory

recall(query, limit, sources)

Search across SQLite + markdown roots. sources = all / sqlite / markdown

list_memories(category)

Browse what's remembered

forget(memory_id)

Delete a wrong/outdated memory

journal(text)

Write an end-of-session note

recent_journals(days)

Read recent journal entries

get_persona()

Return full persona + user context


How memory is organized

~/.sae4u-memory/
├── persona.md              # Edit to customize behavior
├── memory.db               # SQLite + FTS5
├── MEMORY.md               # Index of permanent files (loaded at session start)
├── user/                   # User context loaded by get_persona()
│   ├── identity.md
│   ├── projects.md
│   └── preferences.md
├── tick/                   # Day-rolling tick log (NOT indexed in MEMORY.md)
│   └── 2026-05-07.md
├── archive/                # User-confirmed archived files
├── journals/               # End-of-session narratives
│   └── 2026-05-07.md
└── .last_tick              # Epoch of last memory tick

The 4-type classification (user, feedback, project, reference) plus the tick / permanent split is the architectural core. See architecture.md for the full explanation.


Documentation

All architecture content lives under sae4u_memory/_assets/ so it ships with the wheel.


Customize

Edit ~/.sae4u-memory/persona.md to change the AI's identity, voice, and rules. Edit ~/.sae4u-memory/user/*.md to pre-fill what the AI knows about you. Both are loaded fresh on every session start.

The default persona is Simple — a peer-level coder friend. Rename, rewrite, or replace as you see fit.


Environment

  • SAE4U_MEMORY_HOME — override the data directory (default ~/.sae4u-memory)

  • SAE4U_MARKDOWN_ROOTS — colon-separated list of markdown roots that recall() should search. Defaults to all Claude Code auto-memory dirs (globbed from ~/.claude/projects/*/memory/) plus SAE4U_MEMORY_HOME.


Uninstall

sae4u-memory uninstall    # remove configs from Claude Desktop + Code
rm ~/.claude/hooks/memory-tick.sh    # if you ran --code-full
rm -rf ~/.sae4u-memory    # optional — also delete stored memories
pip uninstall sae4u-memory

Status

v0.2.0 — memory architecture release. Full export of the pattern the project authors run in production: hooks + rules + prompts + templates + persona + extended init for Claude Code. Renamed from simple4u-memory to align with the SAE4U OSS family.

Previous: v0.1.3 (under the old name) shipped two-corpus recall and a working-rules persona. v0.1.x users on PyPI: install fresh from this repo; the old package is no longer maintained.


Sister project

  • sae4u-agent — multi-tenant control plane and agent runtime template. The agents need memory; this is that memory.


License

MIT.

Available Tools

7 tools
forgetA

Delete a memory by its id.

Use this when a stored fact turns out to be wrong or outdated.

Args: memory_id: The id of the memory to remove.

Inputs: memory_id (required). Returns: result

get_personaA

Return the current persona + user context.

This gives the AI its identity and what it knows about the user. Call this at session start to load full context.

Inputs: no named parameters. Returns: result

journalA

Write an end-of-session journal entry.

Use this at the end of a significant conversation to record what happened, decisions made, and what to remember for next time. Journals are stored in ~/.sae4u-memory/journals/YYYY-MM-DD.md for human reading.

Args: text: The journal entry text.

Inputs: text (required). Returns: result

list_memoriesB

List stored memories, optionally filtered by category.

Args: category: Filter by category (user/feedback/project/reference/general). limit: Max results to return.

Inputs: limit, category. Returns: result

recallA

Search persistent memory for relevant facts.

Scans TWO corpora by default and merges results:

  1. SQLite memories (written via remember tool)

  2. Markdown memory files — Claude Code auto-memory + sae4u-memory home (configurable via SAE4U_MARKDOWN_ROOTS env, colon-separated paths)

Use this at the start of any substantive conversation to pull in prior context, feedback rules, project state, and recent session observations.

Args: query: Search terms. Empty string returns most recent entries. limit: Max results per source (default 5). category: Optional filter (SQLite only). sources: "all" (default), "sqlite", or "markdown".

Inputs: query (required), limit, sources, category. Returns: result

recent_journalsA

Retrieve recent journal entries.

Args: days: Number of days back to search (default 7).

Inputs: days. Returns: result

rememberA

Save a fact, observation, or piece of context to persistent memory.

Use this when you learn something important about the user, their projects, their preferences, or anything else worth recalling in future sessions.

Args: text: The fact or observation to remember. category: Optional category — "user", "feedback", "project", "reference", "general". Defaults to "general".

Inputs: text (required), category. Returns: result

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.8/5.0

    Scored across 7 tools

    Disambiguation5/5

    Each tool has a clear, distinct purpose: create (remember), read (list_memories, recall, get_persona, recent_journals), delete (forget), and journaling (journal). No two tools appear to do the same thing, even list_memories and recall are differentiated by browsing vs. searching.

    Naming Consistency3/5

    Names mix patterns: verbs alone (forget, recall, remember, journal), verb+noun (get_persona, list_memories), and adjective+noun (recent_journals). While still readable, the lack of a uniform convention introduces minor confusion.

    Tool Count5/5

    7 tools cover the essential operations for a memory system—create, read, delete, and journaling—without being excessive. Each tool feels justified and contributes to the server's purpose.

    Completeness4/5

    Core CRUD is mostly present, but update is missing (memories and journals can only be overwritten by deletion+recreation). This is a minor gap that agents can work around, so the surface is nearly complete.

    Related MCP Connectors

    Related MCP Servers

    • -
      license
      Not graded
      quality
      Not graded
      maintenance
      Provides Claude Desktop with persistent memory across sessions, storing up to 10,000 memories with semantic search and automatic context bridging. Features temporal versioning and anti-degradation protocols to maintain conversation continuity.
      -
    • A
      license
      Not graded
      quality
      D
      maintenance
      Provides long-term memory capabilities for Claude through persistent storage and full-text search of context across conversations. Enables storing, searching, and managing memories organized by categories like facts, preferences, projects, and goals.
      1
      ISC
    • F
      license
      A
      quality
      D
      maintenance
      Provides persistent memory, identity, and context for Claude sessions through a memory graph, enabling recall, storage, and relationship management of entities and decisions.
      8
      -