kore-memory 0.5.1

The memory layer that thinks like a human: remembers what matters, forgets what doesn't, and never calls home.

The memory layer that thinks like a human.
Remembers what matters. Forgets what doesn't. Never calls home.

Install · Quickstart · How it works · API · Changelog · Roadmap

---

Why Kore?

Every AI agent memory tool has the same flaw: they remember everything forever, phone home to cloud APIs, or need an LLM just to decide what's worth storing.

Kore is different.

Feature	Kore	Mem0	Letta	Memori
Runs fully offline	✅	❌	❌	❌
No LLM required	✅	❌	❌	✅
Memory Decay (Ebbinghaus)	✅	❌	❌	❌
Auto-importance scoring	✅ local	✅ via LLM	❌	❌
Memory Compression	✅	❌	❌	❌
Semantic search (50+ langs)	✅ local	✅ via API	✅	✅
Timeline API	✅	❌	❌	❌
Tags & Relations (graph)	✅	❌	✅	❌
TTL / Auto-expiration	✅	❌	❌	❌
MCP Server (Claude, Cursor)	✅	❌	❌	❌
Batch API	✅	❌	❌	❌
Export / Import (JSON)	✅	❌	✅	❌
Agent namespace isolation	✅	✅	✅	❌
Install in 2 minutes	✅	❌	❌	❌

---

✨ Key Features

📉 Memory Decay — The Ebbinghaus Engine

Memories fade over time using the Ebbinghaus forgetting curve. Critical memories persist for months. Casual notes fade in days.

decay = e^(-t · ln2 / half_life)

Every retrieval resets the clock and boosts the decay score — just like spaced repetition in human learning.

🤖 Auto-Importance Scoring

No LLM call needed. Kore scores importance locally using content analysis — keywords, category, length.

"API token: sk-abc123"  →  importance: 5  (critical, never forget)
"Juan prefers dark mode"  →  importance: 4  (preference)
"Meeting at 3pm"  →  importance: 2  (general)

🔍 Semantic Search in 50+ Languages

Powered by local sentence-transformers. Find memories by meaning, not just keywords. Search in English, get results in Italian. Zero API calls.

🗜️ Memory Compression

Similar memories (cosine similarity > 0.88) are automatically merged into richer, deduplicated records. Your DB stays lean forever.

📅 Timeline API

"What did I know about project X last month?" — trace any subject chronologically.

🏷️ Tags & Relations

Organize memories with tags and build a knowledge graph by linking related memories together. Search by tag, traverse relations bidirectionally.

⏳ TTL — Time-to-Live

Set an expiration on any memory. Expired memories are automatically excluded from search, export, and timeline. Run /cleanup to purge them, or let the decay pass handle it.

📦 Batch API

Save up to 100 memories in a single request. Perfect for bulk imports and agent bootstrapping.

💾 Export / Import

Full JSON export of all active memories. Import from a previous backup or migrate between instances.

🔌 MCP Server (Model Context Protocol)

Native integration with Claude, Cursor, and any MCP-compatible client. Exposes save, search, timeline, decay, compress, and export as MCP tools.

🔐 Agent Namespace Isolation

Multi-agent safe. Each agent sees only its own memories, even on a shared server.

---

📦 Install

# Core (FTS5 search only)
pip install kore-memory

# With semantic search (50+ languages, local embeddings)
pip install kore-memory[semantic]

# With MCP server (Claude, Cursor integration)
pip install kore-memory[semantic,mcp]

---

🚀 Quickstart

# Start the server
kore
# → Kore running on http://localhost:8765

# Save a memory
curl -X POST http://localhost:8765/save \
  -H "Content-Type: application/json" \
  -H "X-Agent-Id: my-agent" \
  -d '{"content": "User prefers concise responses in Italian", "category": "preference"}'

# → {"id": 1, "importance": 4, "message": "Memory saved"}
#   (importance auto-scored: preference category + keyword "prefers")

# Search — any language
curl "http://localhost:8765/search?q=user+preferences&limit=5" \
  -H "X-Agent-Id: my-agent"

# Save with TTL (auto-expires after 48 hours)
curl -X POST http://localhost:8765/save \
  -H "Content-Type: application/json" \
  -H "X-Agent-Id: my-agent" \
  -d '{"content": "Deploy scheduled for Friday", "category": "task", "ttl_hours": 48}'

# Batch save (up to 100 per request)
curl -X POST http://localhost:8765/save/batch \
  -H "Content-Type: application/json" \
  -H "X-Agent-Id: my-agent" \
  -d '{"memories": [
    {"content": "React 19 supports server components", "category": "project"},
    {"content": "Always use parameterized queries", "category": "decision", "importance": 5}
  ]}'

# Tag a memory
curl -X POST http://localhost:8765/memories/1/tags \
  -H "Content-Type: application/json" \
  -H "X-Agent-Id: my-agent" \
  -d '{"tags": ["react", "frontend"]}'

# Search by tag
curl "http://localhost:8765/tags/react/memories" \
  -H "X-Agent-Id: my-agent"

# Link two related memories
curl -X POST http://localhost:8765/memories/1/relations \
  -H "Content-Type: application/json" \
  -H "X-Agent-Id: my-agent" \
  -d '{"target_id": 2, "relation": "depends_on"}'

# Timeline for a subject
curl "http://localhost:8765/timeline?subject=project+alpha" \
  -H "X-Agent-Id: my-agent"

# Run daily decay pass (cron this)
curl -X POST http://localhost:8765/decay/run \
  -H "X-Agent-Id: my-agent"

# Compress similar memories
curl -X POST http://localhost:8765/compress \
  -H "X-Agent-Id: my-agent"

# Export all memories (JSON backup)
curl "http://localhost:8765/export" \
  -H "X-Agent-Id: my-agent" > backup.json

# Cleanup expired memories
curl -X POST http://localhost:8765/cleanup \
  -H "X-Agent-Id: my-agent"

---

🧠 How It Works

Save memory
    │
    ▼
Auto-score importance (1–5)
    │
    ▼
Generate embedding (local, offline)
    │
    ▼
Store in SQLite with decay_score = 1.0
    │
    │   [time passes]
    │
    ▼
decay_score decreases (Ebbinghaus curve)
    │
    ▼
Search query arrives
    │
    ▼
Semantic similarity scored
    │
    ▼
Filter out forgotten memories (decay < 0.05)
    │
    ▼
Re-rank by effective_score = similarity × decay × importance
    │
    ▼
Access reinforcement: decay_score += 0.05
    │
    ▼
Return top-k results

Memory Half-Lives

Importance	Label	Half-life
1	Low	7 days
2	Normal	14 days
3	Important	30 days
4	High	90 days
5	Critical	365 days

Each retrieval extends the half-life by +15% (spaced repetition effect).

---

📡 API Reference

Core

Method	Endpoint	Description
POST	/save	Save a memory (auto-scored). Supports ttl_hours for auto-expiration
POST	/save/batch	Save up to 100 memories in one request
GET	/search?q=...	Semantic search with pagination (limit, offset)
GET	/timeline?subject=...	Chronological history with pagination
DELETE	/memories/{id}	Delete a memory

Tags

Method	Endpoint	Description
POST	/memories/{id}/tags	Add tags to a memory
DELETE	/memories/{id}/tags	Remove tags from a memory
GET	/memories/{id}/tags	List tags for a memory
GET	/tags/{tag}/memories	Search memories by tag

Relations

Method	Endpoint	Description
POST	/memories/{id}/relations	Create a relation to another memory
GET	/memories/{id}/relations	List all relations (bidirectional)

Maintenance

Method	Endpoint	Description
POST	/decay/run	Recalculate decay scores + cleanup expired
POST	/compress	Merge similar memories
POST	/cleanup	Remove expired memories (TTL)

Backup

Method	Endpoint	Description
GET	/export	Export all active memories (JSON)
POST	/import	Import memories from a previous export

Utility

Method	Endpoint	Description
GET	/health	Health check + capabilities

Interactive docs: http://localhost:8765/docs

Headers

Header	Required	Description
X-Agent-Id	No	Agent namespace (default: "default")
X-Kore-Key	On non-localhost	API key (auto-generated on first run)

Categories

general · project · trading · finance · person · preference · task · decision

Save Request Body

{
  "content": "Memory content (3–4000 chars)",
  "category": "general",
  "importance": 1,
  "ttl_hours": null
}

Field	Type	Default	Description
content	string	required	Memory text (3–4000 chars)
category	string	"general"	One of the categories above
importance	int (1–5)	1	1 = auto-scored, 2–5 = explicit
ttl_hours	int | null	null	Auto-expire after N hours (1–8760). Null = never expires

---

⚙️ Configuration

Env Var	Default	Description
KORE_DB_PATH	data/memory.db	Custom database path
KORE_HOST	127.0.0.1	Server bind address
KORE_PORT	8765	Server port
KORE_LOCAL_ONLY	0	Skip auth for localhost requests
KORE_API_KEY	auto-generated	Override API key
KORE_CORS_ORIGINS	(empty)	Comma-separated allowed origins
KORE_EMBED_MODEL	paraphrase-multilingual-MiniLM-L12-v2	Sentence-transformers model
KORE_MAX_EMBED_CHARS	8000	Max chars sent to embedder (OOM protection)
KORE_SIMILARITY_THRESHOLD	0.88	Cosine threshold for compression

---

🔌 MCP Server

Kore ships with a native Model Context Protocol server for direct integration with Claude, Cursor, and any MCP-compatible client.

# Install with MCP support
pip install kore-memory[mcp]

# Run the MCP server (stdio transport, default)
kore-mcp

Available MCP Tools

Tool	Description
memory_save	Save a memory with auto-scoring
memory_search	Semantic or full-text search
memory_timeline	Chronological history for a subject
memory_decay_run	Recalculate decay scores
memory_compress	Merge similar memories
memory_export	Export all active memories

Claude Desktop Configuration

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "kore-memory": {
      "command": "kore-mcp",
      "args": []
    }
  }
}

Cursor / Claude Code Configuration

Add to your .claude/settings.json or MCP config:

{
  "mcpServers": {
    "kore-memory": {
      "command": "kore-mcp"
    }
  }
}

---

🐍 Python SDK

Kore ships with a built-in Python client SDK — type-safe, zero dependencies beyond httpx, supports both sync and async.

pip install kore-memory

Sync

from src.client import KoreClient

with KoreClient("http://localhost:8765", agent_id="my-agent") as kore:
    # Save
    result = kore.save("User prefers dark mode", category="preference")
    print(result.id, result.importance)

    # Search
    results = kore.search("dark mode", limit=5)
    for mem in results.results:
        print(mem.content, mem.decay_score)

    # Tags
    kore.add_tags(result.id, ["ui", "preference"])
    kore.search_by_tag("ui")

    # Relations
    other = kore.save("Use Tailwind for styling", category="decision")
    kore.add_relation(result.id, other.id, "related")

    # Maintenance
    kore.decay_run()
    kore.compress()
    kore.cleanup()

    # Export
    backup = kore.export_memories()

Async

from src.client import AsyncKoreClient

async with AsyncKoreClient("http://localhost:8765", agent_id="my-agent") as kore:
    result = await kore.save("Async memory", category="project")
    results = await kore.search("async", limit=5)
    await kore.decay_run()

Error Handling

from src.client import KoreClient, KoreValidationError, KoreRateLimitError

with KoreClient() as kore:
    try:
        kore.save("ab")  # too short
    except KoreValidationError as e:
        print(f"Validation error: {e.detail}")
    except KoreRateLimitError:
        print("Slow down!")

Exception hierarchy: KoreError → KoreAuthError | KoreNotFoundError | KoreValidationError | KoreRateLimitError | KoreServerError

SDK Methods

Method	Description
save(content, category, importance, ttl_hours)	Save a memory
save_batch(memories)	Batch save (up to 100)
search(q, limit, offset, category, semantic)	Semantic or FTS search
timeline(subject, limit, offset)	Chronological history
delete(memory_id)	Delete a memory
add_tags(memory_id, tags)	Add tags
get_tags(memory_id)	Get tags
remove_tags(memory_id, tags)	Remove tags
search_by_tag(tag, limit)	Search by tag
add_relation(memory_id, target_id, relation)	Create relation
get_relations(memory_id)	Get relations
decay_run()	Run decay pass
compress()	Merge similar memories
cleanup()	Remove expired memories
export_memories()	Export all memories
import_memories(memories)	Import memories
health()	Health check

---

🔐 Security

• API key — auto-generated on first run, saved as data/.api_key (chmod 600)
• Agent isolation — agents can only read/write/delete their own memories
• SQL injection proof — parameterized queries throughout
• Timing-safe key comparison — secrets.compare_digest
• Input validation — Pydantic v2 on all endpoints
• Rate limiting — per IP + path, configurable limits
• Security headers — X-Content-Type-Options, X-Frame-Options, CSP, Referrer-Policy
• CORS — restricted by default, configurable via KORE_CORS_ORIGINS
• FTS5 sanitization — special characters stripped, token count limited
• OOM protection — embedding input capped at 8000 chars

---

🗺️ Roadmap

• FTS5 full-text search
• Semantic search (multilingual)
• Memory Decay (Ebbinghaus)
• Auto-importance scoring
• Memory Compression
• Timeline API
• Agent namespace isolation
• API key authentication
• Rate limiting
• Security headers & CORS
• Export / Import (JSON)
• Tags & Relations (knowledge graph)
• Batch API
• TTL / Auto-expiration
• MCP Server (Claude, Cursor)
• Pagination (offset + has_more)
• Centralized config (env vars)
• OOM protection (embedder)
• Vector index cache
• Python client SDK (sync + async)
• npm client SDK
• Web dashboard (localhost UI)
• PostgreSQL backend
• Embeddings v2 (multilingual-e5-large)

---

🤝 Built with OpenClaw

Kore was developed and is actively used inside OpenClaw — a personal AI agent platform that runs Claude on your own infrastructure.

OpenClaw uses Kore as its persistent memory layer: every important conversation, decision, and preference gets stored, scored, and retrieved semantically across sessions.

If you're building AI agents with OpenClaw, Kore integrates natively — just point your skill at http://localhost:8765.

---

🛠️ Development

git clone https://github.com/auriti-web-design/kore-memory
cd kore-memory
python -m venv .venv && source .venv/bin/activate
pip install -e ".[semantic,dev]"
pytest tests/ -v

---

📄 License

MIT © Juan Auriti

---

_{Built for AI agents that deserve better memory.
Developed and battle-tested with OpenClaw — the personal AI agent platform.}