Edgemem

Team memory for Claude Code — store your conventions, decisions, and context in the cloud so every agent session starts with full project knowledge. No more repeating yourself.

npm tests license

---

The problem

Claude Code forgets everything when a session ends. Every day, every developer re-explains the same things:

• Which ORM the project uses
• Which patterns are required
• Which architectural decisions were made and why
• What a new dev needs to know on day one

CLAUDE.md helps — but it requires a commit to update, the agent can't write to it, and it grows until it fills the context window.

edgemem fixes this. Memory lives in Supermemory cloud. Every developer shares it. The agent can read and write it. No commits required.

---

How it works

You write a convention once
         ↓
Stored in Supermemory cloud
         ↓
Every Claude Code session → edgemem loads what's relevant automatically
         ↓
Agent learns something new → writes it back to the cloud
         ↓
Next session, next developer → Claude already knows

3 ways Claude receives memory:

Mode	How	Best for
Mode 1 — File sync	edgemem sync pulls files locally → @import in CLAUDE.md	Getting started, simplest setup
Mode 2 — MCP server	Claude has 5 live tools to read/write memory during the session	Active development
Mode 3 — Hook	Memory is injected automatically at session start, no commands needed	Zero-effort, always-on

All three modes share the same Supermemory container — one source of truth.

---

Quick start

1. Install and initialize

npm install -g edgemem

export SUPERMEMORY_API_KEY=sm-...
export EDGEMEM_CONTAINER=myproject-team

npx edgemem init

2. Write your first memory

npx edgemem write "memory/stack.md" "
Database: PostgreSQL 16
ORM: Drizzle (not Prisma)
Package manager: pnpm
Framework: Next.js App Router
"

3. Load memory into Claude

npx edgemem sync   # pull memory → .claude/memory/
claude             # Claude reads it automatically via CLAUDE.md

Every teammate with the same SUPERMEMORY_API_KEY gets the same context immediately.

---

Setup modes

Mode 1 — File sync

Pull memory down as local files and reference them from CLAUDE.md:

npx edgemem sync --output .claude/memory

Add to CLAUDE.md:

@.claude/memory/stack.md
@.claude/memory/conventions.md

Limitation: requires running sync to pick up new memory. Agent cannot write back.

---

Mode 2 — MCP server (recommended)

Claude gets 5 tools for reading and writing memory in real time during every session.

Add .mcp.json to your project root:

{
  "mcpServers": {
    "edgemem": {
      "command": "npx",
      "args": ["@edgemem/mcp"],
      "env": {
        "SUPERMEMORY_API_KEY": "${SUPERMEMORY_API_KEY}",
        "EDGEMEM_CONTAINER": "myproject-team"
      }
    }
  }
}

Claude now has mem_read, mem_write, mem_append, mem_grep, and mem_list available every session.

---

Mode 3 — Hook (zero effort)

Memory is injected automatically at session start. No commands, no prompting.

cp -r examples/mode3-hook/.claude .claude
export EDGEMEM_CONTAINER=myproject-team

---

Built for teams

All developers share the same container. One person writes a convention — everyone's agent knows immediately:

# Developer A — Monday
npx edgemem append "memory/conventions.md" "Use server actions for all mutations" --force

# Developer B — Tuesday, different machine
claude
# → Claude already knows about server actions. No sync. No commit.

Onboarding a new developer:

git clone your-repo
export SUPERMEMORY_API_KEY=sm-...   # from team 1Password
claude
# → Claude knows the entire project context from day one

---

Security

Protected core files

These files are read-only for the agent. Only a human can write to them with --force:

File	Purpose
memory/stack.md	Tech stack and versions
memory/conventions.md	Coding conventions
memory/decisions.md	Architecture decisions
memory/onboarding.md	New developer guide

# Human override
npx edgemem write "memory/stack.md" "updated stack" --force

# Agent attempt → error before any API call is made

PII scanner

Every write and append scans for credentials and redacts them before reaching the cloud:

Pattern	Redacted as
sk_live_*, sk_test_*	[REDACTED_SECRET]
AIzaSy*	[REDACTED_SECRET]
AKIA*	[REDACTED_SECRET]
ghp_*, gho_*, ghs_*	[REDACTED_SECRET]
xoxb-*	[REDACTED_SECRET]
Bearer <token>	[REDACTED_SECRET]
password: <value>	[REDACTED_SECRET]

Write signatures

Every write is stamped with author and timestamp:

<!-- edgemem-entry-start | author: alice | timestamp: 2026-06-08T10:33:10Z -->
Use Drizzle ORM. Run migrations with pnpm db:migrate.
<!-- edgemem-entry-end -->

Author is resolved from EDGEMEM_AUTHOR env var, falling back to $USER.

---

Offline resilience

If Supermemory is unreachable, edgemem falls back to local cache — Claude Code never crashes:

Operation	Behavior
read	Returns latest cached version + warns to stderr
write / append	Writes to local cache + warns to stderr
grep	Returns empty string + warns to stderr
list	Returns empty array

Cache lives at ~/.edgemem/cache/<container>/.

---

Smart context chunking

mem_grep runs a semantic search then returns only the relevant sections — so a large memory file never floods the context window:

1. Splits document into sections by heading or paragraph
2. Scores each section by query relevance (heading match = 3×)
3. Returns top sections within a 4,000-token budget
4. Prepends a warning when sections are dropped

---

Audit log

Every operation is appended to .claude/memory/edgemem.log in JSON Lines format:

{"timestamp":"2026-06-08T10:33:10Z","action":"read","file_path":"memory/stack.md","status":"ok","author":"alice"}
{"timestamp":"2026-06-08T10:33:11Z","action":"write","file_path":"memory/auto-saved.md","status":"pii-redacted","detail":"redacted: stripe-live-key","author":"ci-bot"}
{"timestamp":"2026-06-08T10:33:12Z","action":"read","file_path":"memory/stack.md","status":"cache-hit","author":"bob"}

---

CLI reference

# Setup
npx edgemem init [--container <name>] [--api-key-env <name>]

# Mode 1 — pull memory to local files
npx edgemem sync [--output <dir>] [--container <name>]

# Read / write
npx edgemem read <path> [--container <name>]
npx edgemem write <path> <content> [--container <name>] [--force]
npx edgemem append <path> <content> [--container <name>] [--force]

# Search
npx edgemem grep <query> [--path <path>] [--container <name>]
npx edgemem list [--path <path>] [--container <name>]

# Mode 3 — output memory context for hook injection
npx edgemem inject [--container <name>] [--format context|json]

--force bypasses write protection on core files. Intended for human use only.

---

MCP tools

Tool	Description	Core-file safe?
mem_read	Read a file from team memory	Read-only
mem_write	Write or overwrite a memory file	Requires EDGEMEM_ALLOW_CORE_MUTATION=true
mem_append	Append to a memory file	Requires EDGEMEM_ALLOW_CORE_MUTATION=true
mem_grep	Semantic search with chunked results	Read-only
mem_list	List all memory files	Read-only

---

Memory file conventions

memory/stack.md        — tech stack, versions, tools           [protected]
memory/conventions.md  — coding conventions and patterns       [protected]
memory/decisions.md    — architecture decisions and rationale  [protected]
memory/onboarding.md   — guide for new developers              [protected]
memory/auto-saved.md   — conventions captured automatically    [writable]
memory/<anything>.md   — your own custom files                 [writable]

---

Configuration

Config is resolved in this order (first match wins):

1. Environment variables
2. .clauderc in the project root
3. ~/.edgemem/config.json (global default)

Variable	Purpose
SUPERMEMORY_API_KEY	API key for Supermemory
EDGEMEM_CONTAINER	Container name shared by the team
EDGEMEM_AUTHOR	Identity stamped on every write (falls back to $USER)
EDGEMEM_ALLOW_CORE_MUTATION	Set to true to allow agent writes to protected files

.clauderc:

{
  "container": "myproject-team",
  "apiKeyEnv": "SUPERMEMORY_API_KEY"
}

---

Development

pnpm install
pnpm build   # compile all packages
pnpm test    # run all 167 tests

Package structure

packages/
  core/   @edgemem/core — MemClient, guard, cache, audit, chunker
  mcp/    @edgemem/mcp  — MCP server (5 tools)
  cli/    edgemem       — CLI (init, sync, read, write, append, grep, list, inject)
examples/
  mode1-claudemd/   file sync example
  mode2-mcp/        .mcp.json + CLAUDE.md instructions
  mode3-hook/       .claude/settings.json + auto-save hook

Test coverage

Package	Tests
@edgemem/core	107
@edgemem/mcp	30
edgemem CLI	30
Total	167

---

License

MIT