Skip to content
medyllPublic

About

Human-like memory with progressive decay for AI agents

Resources

Stars

0 stars

Watchers

0 watching

Forks

Latest commit

 

History

147 Commits

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

humemory

Memory for AI agents that forgets like a human — and resurfaces like one.

humemory is a memory engine that does not behave like a database. It behaves like a brain. Traces decay through five levels (full detail → summary → essentials → keywords → lost/merged), recall reinforces them, and — this is the part that matters — the right memory comes back to you before you ask for it.

Most "agent memory" is a searchable log. You query it, it returns rows. humemory's reason to exist is the opposite move: a memory that surfaces the relevant trace on a contextual cue, the way you remember to buy milk when you walk past the shop, not when you run a full-text search for "milk".


Two halves of a brain

humemory is built in two halves. The first was shipped first; the second is what it was always for. Both are built as of Phase 8.

1. Retrospective memory — what was learned ✅ built

Past learnings are encoded, then degraded over time on a human curve:

Level Name Lifespan Holds
L0 full detail fresh (<24h) complete content
L1 summary days deterministic summary; optional LLM enhancement
L2 essential weeks the gist
L3 keywords months lexical retrieval tokens
L4 lost / merged explicit merge source linked to a sibling trace

Recall resists decay. Saillance (mnemonic strength, 0–100) and recall count slow the curve. A photographic flag pins critical traces so they never fade.

Inverse search visits indexed fields in order: L3 keywords → L2 essentials → L1 summary → full content. It collects matches across these fields, then ranks and limits the results. A relaxed pass runs only if the strict pass found nothing. Search does not itself reinforce a trace; use recall for that.

The model has five states, but automatic aging currently stops at L3: the decay calculator does not visit the configured L4 threshold. Aging preserves the original content and derived fields in SQLite, so detailed content remains searchable. See the interactive architecture guide for the overall system and the detailed rules.

A Claude Code Stop hook can queue each completed session instantly; maintenance extracts and stores its learnings afterward, outside the agent's critical path.

2. Prospective memory — what to resurface ✅ built

The second half (see AGENTS.md → Phase 5) is what gives humemory its life:

  • Prospective memory — store an intention that fires on a cue (a time, or an event: opening a file, switching branch, hitting an error), not on a search.
  • Zeigarnik effect — an open loop stays salient near consciousness until it is closed. A git commit is the synaptic release that purges it.
  • Cognitive scripts — context-triggered routines, pre-loaded, ready to run.

Concretely: on SessionStart, humemory reads the open loops and the decayed-but-relevant traces for the current directory/branch and injects them as context — "yesterday you left refactor fn X open" — instead of waiting to be queried.


Quick start

pnpm install
pnpm build:web      # bundle the React front (bun's own bundler, no extra tooling)
pnpm start:api      # API + dashboards → http://localhost:3456
pnpm cli status     # state of the memory palace
pnpm cli sources discover # discover local AI runtimes; reads no sessions
pnpm test           # bun test — backend and React components, one runner

Local AI sources — a non-exhaustive registry

humemory keeps acquisition outside the cognitive core: the registry discovers local producers, while humemory decides what becomes a trace, how it decays, and when it resurfaces. Discovery only checks commands and known data roots; importing historical sessions remains an explicit, opt-in step.

The non-exhaustive catalog currently recognizes:

Runtime Vendor Discovery hints
Claude Code Anthropic claude, ~/.claude
Codex OpenAI codex, ~/.codex
Kimi Code / Kimi Desktop Moonshot AI kimi, ~/.kimi-code, desktop data roots
Mistral Vibe Mistral AI vibe, $VIBE_HOME, ~/.vibe
OpenCode SST opencode, ~/.opencode, ~/.local/share/opencode
Qwen Code Alibaba Cloud qwen, $QWEN_RUNTIME_DIR, $QWEN_HOME, ~/.qwen
Gemini CLI Google gemini, $GEMINI_CLI_HOME, ~/.gemini
GitHub Copilot CLI GitHub copilot, ~/.copilot
Aider Aider-AI aider, ~/.aider.conf.yml
Cursor Anysphere cursor, desktop data roots
Windsurf Cognition windsurf, desktop data roots

An entry means ready to be discovered, not automatically importable. The three parsed historical sources are named explicitly below; every other entry is detection-only. Run pnpm cli sources discover --installed-only for a local inventory without exposing conversation content.

Codex, Kimi Code and OpenCode are parsed. They all import into the same queue the live hooks write to. Kimi uses its documented session index and wire under $KIMI_CODE_HOME; OpenCode is read through its public db and export CLI commands rather than coupling humemory to the SQLite schema:

pnpm cli sources import-codex --dry-run     # what would be queued, writes nothing
pnpm cli sources import-codex --since 7     # the last week (default)
pnpm cli sources import-codex --all         # every rollout ever recorded
pnpm cli sources import-kimi --all
pnpm cli sources import-opencode --all
pnpm cli sources setup --dry-run            # preview MCP registration in all four clients
pnpm cli sources setup                      # register MCP in Claude Code, Codex, Kimi Code and OpenCode
pnpm cli sources setup --claude             # configure Claude Code only (user scope)
pnpm cli sources setup --codex              # configure Codex only

The resident maintenance loop sweeps new sessions from all three producers every 15 minutes. sources setup merge-adds a humemory MCP entry without removing existing servers and pins each client identity (claude, codex, kimi or opencode) plus the absolute shared database path.

Client flags can be combined, for example sources setup --codex --kimi. Claude Code uses the user-scoped ~/.claude.json; setup preserves its per-project state and other servers. Use --claude-config <path> for a different user config file. The repository's .mcp.json remains a project-scoped alternative; Claude Code gives local and project definitions priority over the user entry when they share the same server name. See Claude Code's MCP scopes. Codex uses $CODEX_HOME/config.toml (default ~/.codex/config.toml); setup preserves other settings and comments, backs up changed files to a sibling .bak file, and writes atomically. Running it again with the same settings changes nothing. Invalid files, remote humemory servers in Codex, and TOML layouts that cannot be safely edited (such as inline server definitions) are refused without rewriting the file. Codex's configuration format is documented in the official MCP guide.

Importing only queues; the worker still decides what becomes a trace. Jobs are keyed on session, so re-importing is idempotent and a thread that grew since the last pass contributes only its new messages. Threads codex spawned for itself (judges, reviews) are excluded unless --include-subagents — they are not sessions a human had. Model reasoning and tool calls are dropped like tool_result already is: a learning is what was decided, not how it was found.

A trace is dated on the transcript's own clock, not on the sweep's: a rollout read three weeks late encodes on the day it was lived, and arrives already degraded to the level that age warrants. Without this a bulk import collapses every session into a single import day, and the store loses the timeline that day exists to hold.

The React app is served at / (and /app). The original vanilla dashboard has been removed — the React front reached parity first, and git keeps the old one if it is ever needed.

The visualisations are wrapped, not rewritten: d3 owns its SVG subtree and three.js its WebGL canvas, so they stay imperative inside a useEffect. Only the parts built from innerHTML strings — the trace dashboard, the replay player, the merge panel — became JSX. Each visualisation is code-split and loaded on demand; three.js alone is half a megabyte, and nobody who never opens the promenade should download it.

Run pnpm build:web before pnpm start:api, or / answers 503 telling you so.

Open loops (prospective memory)

# arm a loop, with a file cue and a weekly reminder
pnpm cli intent add "refactor token validation" -d ./src/auth \
  -c 'event:file_open:src/auth/service.ts' -c 'cron:0 9 * * 1' -e 2026-12-31

pnpm cli intent list              # armed loops (--all for every status)
pnpm cli intent close loop-a1b2c3d4 --commit deadbee
pnpm cli intent resolve           # expire overdue loops, fire due deadlines

Cue formats: time:<ISO>, cron:<5-field expr>, event:file_open:<path>, event:branch_switch:<branch>, event:error_pattern:<regex>.

Cron expressions use UTC and five numeric fields: minute (0–59), hour (0–23), day of month (1–31), month (1–12), weekday (0–6, Sunday = 0). Fields accept *, numbers, ranges, lists and positive steps, for example */15 or 1-9/2. The CLI, dashboard cue form and HTTP API reject malformed expressions before storing them. For example, 0 9 * * 1 fires on Mondays at 09:00 UTC; 0 9 * * 1, is an error.

Directories are resolved to absolute paths on write — a loop armed on a relative path would never match the SessionStart hook, which looks the project up by process.cwd().

Over HTTP: POST /intentions, GET /intentions?status=armed&directory=…, GET /intentions/:id, POST /intentions/:id/close, POST /intentions/:id/fire, DELETE /intentions/:id, POST /cues, GET /cues, POST /events, POST /cues/resolve.

Closing loops from git

git config core.hooksPath .githooks   # in this repo

For another project, copy .githooks/post-commit into it and point HUMEMORY_HOME at your humemory checkout — the database is shared across projects, the code is not:

export HUMEMORY_HOME=/path/to/humemory

Write Closes loop-a1b2c3d4 in a commit message and that loop is closed, its SHA recorded, its remaining cues cancelled. Everything else is only suggested: the hook scores the overlap between the files you touched and the loop's text, and prints candidates. It never closes on a guess — closing the wrong loop costs more than leaving one open.

💡 Loops this commit may have touched:
   loop-e99166cd — Refactor the auth middleware
      overlaps: auth, middleware

   To close: pnpm cli intent close loop-e99166cd

Wiring the Claude Code hooks

Two hooks, both optional and both fail-open. Stop only writes the raw session to a durable local queue; it never waits for a model or a network request:

// ~/.claude/settings.json
{
  "hooks": {
    // start of session: injects open loops + relevant decayed traces as context
    "SessionStart": [{ "matcher": "", "hooks": [
      { "type": "command", "command": "bun /path/to/humemory/scripts/hook-session-start.ts" }
    ]}],
    // end of session: queues the transcript for asynchronous maintenance
    "Stop": [{ "matcher": "", "hooks": [
      { "type": "command", "command": "bun /path/to/humemory/scripts/hook-session.ts" }
    ]}]
  }
}

SessionStart reads the current directory and git branch, expires stale loops, fires any due time cues, and writes a markdown block on stdout — which Claude Code injects into the session. Nothing relevant means nothing written.

Process queued sessions independently from the agent flow:

pnpm maintenance

The default maintenance path is deterministic and network-free. To opt into Claude as an asynchronous quality enhancement, set HUMEMORY_MAINTENANCE_LLM=anthropic and ANTHROPIC_API_KEY; quota errors and timeouts fall back to the deterministic extractor. A queue item is deleted only after its extracted memories are committed successfully.

Without an API key, HUMEMORY_MAINTENANCE_LLM=codex uses the logged-in codex CLI instead — same fallback, no key, your agent subscription pays. Raise HUMEMORY_MAINTENANCE_TIMEOUT_MS to ~60000: an agent turn costs seconds of start-up before the first token. The adapter runs codex --ephemeral and --ignore-user-config deliberately: a persisted rollout would be re-ingested as a trace later, and a humemory hook wired into codex would re-enter humemory mid-maintenance. Expect ~12k tokens of agent preamble per call regardless of trace size — this buys summary quality, not economy.

The queue directory is the whole contract, and it is inspectable at any time:

Entry Meaning
<id>.json a session waiting to be encoded, keyed on session — not on transcript content, since Stop resends a longer transcript every turn
<id>.json.processing claimed by the running worker; a newer transcript may land on the free <id>.json slot meanwhile, and survives
checkpoints/<id>.json how many messages of that session are already encoded, so a resent transcript only contributes its delta
<id>.dead.json gave up after maxAttempts (5), or unparseable on disk; never retried, never deleted
.worker.lock single-worker token; a lock left by a dead worker is reclaimed atomically after 5 min
Env var Default Effect
HUMEMORY_DB data/humemory.db database path
HUMEMORY_QUEUE data/maintenance-queue durable raw-session inbox
HUMEMORY_MAINTENANCE_LLM none optional enhancement (anthropic, codex)
HUMEMORY_MAINTENANCE_TIMEOUT_MS 8000 model timeout; never affects the agent hook. codex needs ~60000
HUMEMORY_LLM_MODEL provider default model id; mini models are rejected on ChatGPT accounts
HUMEMORY_DIR cwd mental place to scope loops and traces to
HUMEMORY_SESSION_BUDGET 10 max items listed per section
HUMEMORY_SAILLANCE_MIN 60 salience floor for recalling a decayed trace
HUMEMORY_VERBOSE unset 1 logs a one-line summary on stderr

Serving the API safely

The database holds every learning trace and open loop across all your projects, and the API can read, alter and delete all of it. Treat the port as sensitive.

Env var Default Effect
PORT 3456 API/dashboard port
HUMEMORY_HOST 127.0.0.1 listen address — loopback only unless you change it
HUMEMORY_API_TOKEN unset when set, required on every data route (Authorization: Bearer … or X-Humemory-Token)
CORS_ORIGINS http://localhost:3456 comma-separated exact origins, honoured when NODE_ENV=production
HUMEMORY_VERBOSE_ERRORS unset 1 returns real error messages instead of a correlation id — local debugging only

Defaults are private. The server binds 127.0.0.1, so nothing on your network can reach it. Without HUMEMORY_API_TOKEN it starts anyway and warns, because on loopback the OS is the boundary.

Exposing it is deliberate. Setting HUMEMORY_HOST to anything but loopback without a token makes the server refuse to start rather than quietly publish your memory to the LAN:

HUMEMORY_HOST=0.0.0.0 HUMEMORY_API_TOKEN="$(openssl rand -hex 32)" pnpm start:api

The dashboard asks for that token behind the 🔑 button in its header and keeps it in localStorage. /health and the static assets stay open so a probe and the page itself still load.

A token is not a substitute for the network layer: over anything but loopback, put TLS and a firewall in front of it. The token travels in a header, in clear, over plain HTTP.


Why it exists

A log remembers everything and reminds you of nothing. A human memory forgets most of it and hands you the one thing that matters, at the moment it matters. humemory is an attempt to give an AI agent the second kind.

A memory engine, not an integration bundle

humemory has a narrow job: decide what deserves to become a memory, how that trace changes with time, and when it should return. Everything that brings data in sits outside the cognitive core.

  • Connectors live in a registry. Discovery and future import adapters identify Claude Code, Codex, Kimi, Qwen, Mistral and other local producers; they don't become memory primitives. Adding a source doesn't change decay, recall, trust or cue logic.
  • SQLite owns the truth. Provenance, decay levels, intentions, scripts and review decisions remain queryable and recoverable. Vector embeddings form a second, disposable search lane: humemory can rebuild them, change the embedding model or disable semantic search without putting the memory store at risk.
  • Several agents can share one brain. MCP and source attribution let Claude, Codex, Kimi, OpenCode and future clients use the same store. Every write keeps its agent and device provenance instead of inheriting one vendor's session model.
  • Maintenance stays out of the agent's path. Hooks queue a raw session locally, then exit. A separate worker filters, consolidates and stores it; a slow GPU, a network outage or an exhausted quota doesn't make the agent wait.
  • LLMs are optional, not governors. Decay, salience, recall, cues, scripts, trust and deterministic consolidation work without an API key. A configured model may improve the generated text, but failure always returns to the local deterministic path.
  • Automation stops before judgment. The dreamer files proposals, agent-authored scripts begin as drafts, and contradictions stay inspectable. A model doesn't silently turn a guess into permanent memory.

Historical bulk absorption stays opt-in. sources discover checks commands and known paths without reading conversations. Codex, Kimi Code and OpenCode have explicit import adapters; every other catalog entry remains detection-only, and discovery never pretends otherwise.

Stack

TypeScript · bun:sqlite (WAL) · flexsearch (lexical index, heuristic ranking — not a BM25 implementation) · hono (API) · commander (CLI) · @anthropic-ai/sdk (optional maintenance adapter).


Usage

Installation

pnpm install

New installations keep writable state in the user profile. Existing checkouts with data/humemory.db keep that location; nothing is moved automatically. HUMEMORY_DATA_DIR selects another data root, while HUMEMORY_DB, HUMEMORY_QUEUE and HUMEMORY_MODEL_CACHE override individual locations.

To relocate a project's memory, preview the mapping before applying it:

pnpm cli remap-project /old/project /new/project
pnpm cli remap-project /old/project /new/project --apply --backup /backups/before-remap.db

The backup includes committed SQLite WAL contents. See portability and recovery guarantees for cron time zones, model downloads, queue recovery and the limits of the platform checks.

CLI Commands

The CLI provides several commands to interact with humemory:

  • Encode a new memory trace:

    pnpm cli encode "Your memory content here"

    Options:

    • -d, --directory <dir>: Mental space (project)
    • -s, --session <id>: Encoding context
    • -k, --keywords <tags>: Retrieval cues (comma-separated)
    • -l1, --level1 <summary>: Summary for consolidation N1
    • -l2, --level2 <essential>: Essential for consolidation N2
    • -l3, --level3 <keywords>: Trace for fast search N3
    • -t, --type <type>: Memory type (episodic/semantic/procedural)
    • --auto: Auto-generate N1/N2/N3 locally; an injected LLM may enhance them
    • --photographic: Photographic mode — disable degradation
  • Search for memory traces:

    pnpm cli search "your query"

    Options:

    • -d, --directory <dir>: Filter by mental space
    • -s, --session <id>: Filter by context
    • -l, --level <max>: Highest indexed field to search (0-4); not a filter on a trace's current state
    • -n, --limit <n>: Number of traces
    • -t, --type <type>: Filter by type (episodic/semantic/procedural)
    • --from <date>: Start date YYYY-MM-DD
    • --to <date>: End date YYYY-MM-DD
    • --min-saillance <n>: Minimum mnemonic strength (0-100)
    • --min-recalls <n>: Minimum reactivations
  • Reactivate a memory trace:

    pnpm cli recall <id>
  • List memory traces:

    pnpm cli list

    Options:

    • -n, --limit <n>: Number of traces
    • -l, --level <level>: Filter by state (0-4)
    • -t, --type <type>: Filter by type (episodic/semantic/procedural)
  • Update decay:

    pnpm cli decay
  • Toggle photographic mode:

    pnpm cli photo <id>

    Options:

    • --off: Disable photographic mode
  • Find similar traces:

    pnpm cli similar <id>

    Options:

    • -n, --limit <n>: Number of results
    • -t, --threshold <n>: Minimum score (0-100)
  • Merge traces:

    pnpm cli merge <sourceId> <targetId>

    Options:

    • --auto: Regenerate merged derived levels locally; an injected LLM may enhance them
  • Delete a memory trace:

    pnpm cli delete <id>
  • Show memory palace status:

    pnpm cli status
  • Import a Claude Code session:

    pnpm cli import-session <file>

    Options:

    • -d, --directory <dir>: Project mental space
    • -n, --max <n>: Max learnings to extract
  • Diagnose the installation:

    pnpm cli doctor

    Prints the runtime, the resolved data/queue/model paths and whether they are writable, the schema and journal mode, the state of both advisory locks, the cached embedding models, and every auxiliary entry point (hooks, MCP server, API, dashboard). Environment overrides are listed by name only — no value is printed, and no memory content is read, so the output is safe to paste into a bug report. --json for a machine-readable report; exit code 1 on a real fault, 0 when everything that failed is merely "not set up yet".

API

Start the API server:

pnpm start:api

The API will be available at http://localhost:3456. You can interact with it using the following endpoints:

  • POST /memories: Add a new memory
  • GET /memories: List memories
  • GET /memories/:id: Fetch a specific memory
  • POST /memories/:id/recall: Bump recall and saillance
  • GET /memories/:id/similar: Find similar memories
  • POST /memories/:id/merge: Merge memories
  • POST /memories/:id/photo: Toggle photographic mode
  • DELETE /memories/:id: Forget a memory
  • GET /search?q=X: Inverse search
  • POST /decay: Run consolidation
  • GET /status: Pool stats

Dashboard

The dashboard is available at http://localhost:3456 when the API server is running. It provides a visual interface to interact with humemory.


Examples

Encoding a memory

pnpm cli encode "Fixed the critical bug in the authentication module" \
  -d "my-project" \
  -k "bug,authentication,critical" \
  -t "episodic" \
  --auto

Searching for memories

pnpm cli search "authentication bug" \
  -d "my-project" \
  --min-saillance 50

Reactivating a memory

pnpm cli recall "memory-id-here"

Listing memories

pnpm cli list -l 0 -t "episodic"

Updating decay

pnpm cli decay

Toggling photographic mode

pnpm cli photo "memory-id-here" --off

Finding similar traces

pnpm cli similar "memory-id-here" -n 3 -t 70

Merging traces

pnpm cli merge "source-memory-id" "target-memory-id" --auto

Deleting a memory

pnpm cli delete "memory-id-here"

Showing memory palace status

pnpm cli status

Importing a Claude Code session

pnpm cli import-session "session-file.txt" -d "my-project" -n 5

Development

Building the project

pnpm build

Running tests

pnpm test

Watching tests

pnpm test:watch

Running the CLI directly

pnpm cli <command>

Manual consolidation

pnpm consolidate

Measuring recall quality

pnpm measure:recall

Runs a frozen corpus of 26 traces at controlled ages against 14 queries and prints, per query, what came back and what was missed — plus which open loops come due at a given instant, and what a session actually opens with. The suite proves the machinery works; this asks the question the machinery exists for: does the right memory come back. tests/relevance.test.ts turns the same measurement into a regression floor.

Thresholds there are floors recording current behaviour, not targets. Raising one is a result; lowering one needs a reason in the commit that lowers it.

Measuring cost at scale

pnpm bench:scale

loadIntoMemory() reads every trace and rebuilds the whole search index. It runs in the store's constructor — so every CLI command, every SessionStart hook and every post-commit hook pays it — and again inside search() whenever another process has committed since the last load. This measures what that costs as the corpus grows. --sizes=250,1000,5000 to choose the points, --json for the raw rows.

Verifying the published package

pnpm verify:package

Builds the archive, installs it into a temporary directory outside the checkout — under a path containing a space and an accent — and drives the CLI, the Stop hook, maintenance, the MCP server and the API from there against a virgin profile. Nothing may reach back into the source tree, so a files list that forgets a source an auxiliary entry point imports fails here rather than days later on a user's machine. Runs on Linux, macOS and Windows in CI.


Concepts

Field Cognitive term (French, as in the code) Meaning
createdAt Encodage trace formation
lastRecalled Dernière réactivation last conscious retrieval
recallCount Réactivations recalls (reinforce)
saillance Force mnésique trace strength 0–100
decayRate Taux d'oubli degradation speed
sessionId Contexte d'encodage encoding context
directory Lieu mental conceptual space (project)
currentLevel État de consolidation decay stage 0–4
keywords Indices de récupération retrieval cues
memoryType Type episodic / semantic / procedural

Automatic decay thresholds: L0→L1 24h · L1→L2 168h · L2→L3 720h, before slowdown. L4 is configured at 2160h but is not reached by automatic aging. Age is measured from the more recent creation or recall. Slowdown is min((1 + recallCount * 0.3) × (saillance >= 70 ? 1.5 : 1) × (verified ? 1.5 : 1), 2.5). Content length and keyword count affect the stored decayRate, which the level calculator currently does not use. photographic: true returns L0.

Memory types: episodic (events), semantic (facts), procedural (skills).


Roadmap

✅ Done — Sprints 1–4

  • Core decay + inverse search; bun:sqlite store (WAL, write-queue serialization)
  • CLI + Hono API + web dashboard ("palais de mémoire")
  • Consolidation entry point for an external scheduler (example: 0 3 * * *); the API's 15-minute maintenance loop imports and encodes sessions, not trace decay
  • Deterministic L1/L2/L3 generation; optional injected LLM enhancement
  • Similar-detection + merge (L4); enriched search (type/period/saillance/recalls)
  • Photographic mode; Claude Code Stop hook → durable async maintenance queue

🎯 Phase 5 — Prospective memory (the destiny)

Corrected plan in PHASE5_PLAN.md. Summary:

  • 5.0 Preconditions — cross-process SQLite advisory lock and injectable event bus in the test env, both shipped (S5-00a, S5-00b).
  • 5.1 Data model — dedicated intentions table (not a new MemoryType, intentions don't follow the retrospective decay curve) + cues table with typed trigger_spec. One intention → N cues.
  • 5.2 Cue resolver — time cues (ISO/cron) and event cues (file_open, branch_switch, error_pattern). Decay rule: armed → saillance pinned at 100; fired not closed → −10 saillance points/day from firedAt; closed → archived. This is separate from retrospective trace aging.
  • 5.3 Hooks — SessionStart injects context (scripts/hook-session-start.ts, budget via HUMEMORY_SESSION_BUDGET); git post-commit closes loops via the explicit Closes loop-<id> marker, and only suggests on file-overlap.
  • 5.4 CLI/API — pnpm cli intent {add,list,close,fire,resolve}, POST /intentions, POST /cues, POST /events, POST /cues/resolve.

Phases 6–8 shipped — trust and contradictions, reviewed dream proposals, MCP, optional vector search, and cognitive scripts. See the detailed shipped status in AGENTS.md. Cognitive scripts are Phase 8, not deferred work.

🛣️ Beyond

  • Shared multi-project DB with concurrency lock (WAL + advisory) — done (Sprint 5 / S5-00a)
  • Other-agent import adapters; export/import memories between projects

Known issues

  • SQLite multi-process: advisory lock — fixed in Sprint 5 (S5-00a): WAL + write-queue (Sprint 4) plus file-based cross-process AdvisoryLock.
  • tests/fixtures/ missing — closed (S5-00b): tests/fixtures/*.json + tests/helpers/fixtures.ts. Shared corpora live there; a one-off case a test is specifically about stays inline.
  • vitest.config.ts orphaned — closed: the file is gone, the suite runs under bun test.
  • tsc global can shadow local — pnpm build is tsc -p tsconfig.json.

Notes

  • Shared DB: resolved by src/core/paths.ts (legacy checkout data/humemory.db, otherwise the OS user data directory, with environment overrides) · API port 3456 (PORT env)
  • Stack: TypeScript · bun:sqlite · flexsearch · hono · commander · @anthropic-ai/sdk
  • CLAUDE.md is a thin Claude-Code-specific quick-start that delegates to AGENTS.md; AGENTS.md remains the canonical source of truth.

About

Human-like memory with progressive decay for AI agents

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages