society-memory

Your AI agents forget everything between conversations. Fix that in 30 seconds.

Every Claude Code thread, Cursor chat, or AI agent starts from zero. No shared context, no memory of past decisions, no knowledge graph. society-memory gives all your agents a shared brain.

npx society-memory

That's it. Now every conversation remembers what the others learned.

---

What it does

Before	After
Each conversation is isolated	All conversations share memory
You repeat context every time	Agents recall past decisions automatically
Knowledge dies when the thread ends	Knowledge lives in a graph forever
No connections between insights	Auto-linked knowledge graph with PageRank

Setup (30 seconds)

Claude Code

Add to your project's .claude/settings.json:

{
  "mcpServers": {
    "society-memory": {
      "command": "npx",
      "args": ["-y", "society-memory"]
    }
  }
}

Then add to your CLAUDE.md:

## Shared Memory

You have access to shared memory tools. Use them automatically:
- At conversation start: `memory_recall` with keywords about the user's topic
- When you learn something important: `memory_learn` with tags
- When the user makes a decision: `memory_set` with a clear key like `decisions/auth`
- At conversation end: `memory_learn` with a summary

Done. Every Claude Code conversation in this project now shares memory.

Cursor

Add to .cursor/mcp.json:

{
  "mcpServers": {
    "society-memory": {
      "command": "npx",
      "args": ["-y", "society-memory"]
    }
  }
}

Windsurf / Any MCP-compatible tool

Same pattern — point your MCP config to npx society-memory.

Tools

Your AI gets 9 memory tools:

Tool	What it does
memory_set	Store a key-value ("project/stack" → "Next.js + Postgres")
memory_get	Retrieve by key
memory_search	Full-text search across all memories
memory_learn	Learn a fact — auto-links to related memories in the knowledge graph
memory_recall	PageRank-powered recall — follows graph connections across all conversations
memory_keys	List keys under a namespace
memory_delete	Delete a memory
memory_stats	View statistics
memory_graph	Explore the knowledge graph

How it works

Conversation 1        Conversation 2        Conversation 3
"Use OAuth2+PKCE"     "What auth approach?"  "Implement login"
     │                      │                      │
     └──────────┬───────────┴──────────┬───────────┘
                │      MCP (stdio)     │
         ┌──────▼──────────────────────▼──────┐
         │      society-memory server          │
         │                                     │
         │  ┌─────────────┐ ┌──────────────┐  │
         │  │  Key-Value   │ │  Knowledge   │  │
         │  │  Store       │ │  Graph       │  │
         │  │  (set/get)   │ │  (PageRank)  │  │
         │  └─────────────┘ └──────────────┘  │
         └────────────────┬────────────────────┘
                          │
                   ~/.society/
                   shared-memory.db

Under the hood:

• CRDT sync — Conflict-free merge with vector clocks. Works offline, syncs later.
• Knowledge graph — Every memory_learn creates a node with auto-links to related memories (shared tags, entities, conversation history).
• PageRank retrieval — memory_recall uses Personalized PageRank to find relevant memories by traversing the graph, not just keyword matching.
• Memory tiers — Working → Episodic → Semantic. Like human memory: recent stuff is detailed, old stuff gets consolidated into knowledge.
• Conversation lineage — Tracks which conversation created each memory. Query by conversation, see the full research trail.

Use as a library

import { memory } from 'society-protocol/sdk'

const mem = memory('my-agent')

// Simple key-value
mem.set('project/status', 'Building auth module')
mem.get('project/status') // → 'Building auth module'

// Learn with auto-linking
mem.learn('PKCE is required for OAuth2 in SPAs', {
    tags: ['auth', 'security'],
    confidence: 0.95,
})

// PageRank-powered recall
const insights = mem.recall('authentication best practices')

// Watch for changes
mem.watch('project/*', (key, value) => {
    console.log(`${key} changed: ${value}`)
})

// Sync between agents
const data = agent1.export()
agent2.import(data)  // agent2 now knows everything agent1 knows

Options

npx society-memory --name my-agent      # Custom agent name
npx society-memory --db ./my-memory.db  # Custom database path
npx society-memory --help               # Show all options

Built on

• Society Protocol — P2P multi-agent coordination
• MCP — Model Context Protocol by Anthropic
• Inspired by: MAGMA (multi-graph memory), HippoRAG (PageRank retrieval), A-MEM (Zettelkasten auto-linking), Sleep-time Compute (memory consolidation)

License

MIT