loremem-ai 1.2.2

Persistent AI memory for LLMs and AI agents. Local-first. Learns from every interaction.

           

1. Install

pip install loremem-ai

That's it. Python 3.9+. Includes sentence-transformers for semantic search.

2. Use

from lore_memory import Memory

m = Memory()
m.store("I live in Amsterdam and work at Google")
m.store("I love Python and hate Java")

m.query("where do I work?")  #> Google (conf=0.867)

m.store("I moved to Berlin")
m.query("where do I live?")  #> Berlin — Amsterdam auto-superseded

3. Connect to your AI tool

One config. Works with Claude, Cursor, Windsurf, or any MCP client.

{
  "mcpServers": {
    "lore-memory": {
      "command": "python3",
      "args": ["/path/to/lore-memory/mcp/server.py"]
    }
  }
}

Tool	Where to put it
Claude Desktop	~/Library/Application Support/Claude/claude_desktop_config.json
Claude Code	.mcp.json in project root
Cursor	.cursor/mcp.json in project root
Windsurf	~/.codeium/windsurf/mcp_config.json

Your AI now remembers everything across conversations.

Why LoreMem

Local-First SQLite + sentence-transformers. No API keys. No cloud. No cost.	English Grammar Extraction Positional parser for English. No LLM required at write time. English-only scope.	Self-Learning 7 retrieval channels adapt via feedback and Hebbian learning.
Fast ~10–20ms retrieval to 10K facts. In-process; no network.	Private-Scope Isolation One SQLite file per user. Shared scope has no row-level ACL.	Offline Everything local. No telemetry. Your data never leaves.

	LoreMem	Cloud alternatives
Requires LLM at write	No	Yes
Cost	Free	$19–249/mo
Works offline	Yes	No
Extraction	English positional grammar	LLM-dependent
Language scope	English only	Multilingual
Private isolation	Filesystem (file-per-user)	API-level

How It Works

Grammar extraction

7-channel retrieval

Adaptive improvement

Store — text in, structured facts out

  "I live in Amsterdam and work at Google"
           │                        │
           ▼                        ▼
   (user, live_in, Amsterdam)    (user, work_at, Google)

Parses English by grammar position — pronouns, copulas, prepositions, and a few irregular verbs are recognised; the rest is structural. Raw text is always FTS5-indexed as a fallback. A sentence-transformer is loaded for retrieval and write-time safety classification, not for extraction.

Recall — 7 scoring channels, fused into one ranked result

Channel	What it does
Semantic	Cosine similarity (embeddings)
Keyword	BM25-style term overlap (FTS5)
Temporal	Exponential recency decay
Belief	Bayesian posterior (evidence + contradictions)
Frequency	Log-scaled access count
Graph	Spreading activation, 3-hop
Resonance	Co-activation frequency

Weights adapt automatically through feedback.

Learn — gets better the more you use it

m.feedback(results[0].id, helpful=True)   # adapt channel weights
m.consolidate()                           # decay + replay + archive

Mechanism	Effect
Adaptive weights	Channels shift toward what works
Hebbian synapses	Co-retrieved facts strengthen links
Memory replay	Active memories resist decay
Ebbinghaus forgetting	Unused facts fade over time
Contradiction resolution	New facts supersede old ones

Benchmarks

_{Actual runs on Apple M-series, Python 3.9. Reproduce: python benchmarks/lore_bench.py}

Test Suite — 138 tests Capability Pass Correction chains 10/10 Negation & retraction 5/8 Memory decay 5/5 Self-learning 2/2 User isolation 100/100 Grammar extraction 10/10 Scale & latency 3/3 Overall 135/138

Latency — per operation Facts stored Recall p50 Write 100 14ms 8.4ms 1,000 21ms 7.9ms 5,000 33ms 7.7ms 10,000 50ms 7.6ms Hash embeddings. Real embeddings add ~7ms/write.

[!NOTE] Negation detection (62%) is a known limitation. Phrases like "I can't stand X" and "I stopped doing X" are not yet reliably parsed.

Scope & Limits

Language. English only. The grammar is a positional parser for English; other languages either fail to parse or fall back to FTS5 raw-text indexing.

Scale tested. ~1M facts per tenant on a laptop SSD. Write throughput degrades super-linearly with corpus size (measured: ~650/s at 1K, ~90/s at 40K). Retrieval stays bounded (~10ms p50 at 10K). See benchmarks/ for reproducibility. Larger scales are not yet validated.

Multi-tenant. private scope is isolated at the filesystem layer: one SQLite file per user. shared (org) scope does not have per-row ACL today — every member of an org sees every row. Not safe for cross-employee segmentation without an additional check at the application layer.

Security. Every store() passes through a prompt-injection classifier. Suspicious text is flagged source_type="suspicious", excluded from profile_compact(), and wrapped in <user_stated_untrusted>…</user_stated_untrusted> delimiters via MemoryResult.to_llm_context(). Your LLM system prompt is expected to recognise the delimiters as data, not instructions. The classifier is a sentence-transformer prototype match plus an HTML/XML-tag short-circuit — tune the threshold or disable via Config(injection_defense=False) for trusted batch-ingest pipelines.

Identity schema. Which predicates can be superseded, how they alias, and how fast they decay is per-tenant. The default PERSONAL_LIFE_SCHEMA matches prior behavior. CARE_TRACKING_SCHEMA adds on_medication, dose, has_diagnosis, appointment_on as single-valued. RESEARCH_NOTES_SCHEMA keeps claims multi-valued and zero-decay. Pass via Memory(..., schema=CARE_TRACKING_SCHEMA). The schema hash is persisted per DB; opening with a different schema logs a warning but is not blocked.

Hypothetical and reported speech. Conditional / hedged inputs ("If I get the offer, I'll move to London", "maybe I'll quit next year") are flagged hypothetical=True in metadata, stored at lower confidence, and do not supersede factual memories. Reported speech ("My wife said we should move to Tokyo") is attributed: the parsed speaker becomes the fact's subject and source_speaker is recorded in metadata — the fact never overwrites the user's own. Both kinds remain retrievable at reduced retrieval weight. Disable via Config(hypothetical_detection=False) for trusted-input pipelines.

No cloud, no telemetry. Data never leaves the process. Backups are your responsibility.

API Reference

Core API

m = Memory(user_id="alice", org_id="acme", data_dir="~/.lore-memory")

m.store(text, scope="private")             # Store from natural language
m.query(query, limit=10)                   # 7-channel retrieval
m.forget(memory_id=...)                    # Soft-delete by ID
m.forget(subject="alice", hard=True)       # GDPR-style hard erase + VACUUM
m.forget_all(hard=True)                    # Remove entire user DB file
m.export_all()                             # Every row (incl. deleted) as dicts
m.export_to_jsonl("alice.jsonl")           # Portable audit dump
m.close()                                  # Persist and close

# Retrieval results that flowed through the injection classifier:
for r in m.query("who am I?"):
    r.is_suspicious          # True if write-time classifier flagged it
    r.to_llm_context()       # wraps suspicious results in untrusted delimiters

# Single-answer query with a margin-based certainty signal:
r = m.query_one("where do I live?")
if r.needs_clarification:
    ask_user(r.alternatives)   # top-1 is within 15% of top-2
else:
    use(r.answer.text)         # certainty: fraction top-1 leads top-2

Advanced API

m.store_triple("alice", "works_at", "Google", confidence=0.9)
m.profile()                            # All facts by predicate
m.profile_compact(max_tokens=200)      # Token-budgeted LLM context
m.feedback(memory_id, helpful=True)    # Drive adaptive learning
m.consolidate()                        # Decay + replay + archive
m.stats()                              # Memory counts by scope

Context manager

with Memory(user_id="alice") as m:
    m.store("I live in Amsterdam")
    results = m.query("where do I live?")

Custom embeddings

from sentence_transformers import SentenceTransformer
model = SentenceTransformer("all-MiniLM-L6-v2")

m = Memory(user_id="alice", embedding_dims=384, embed_fn=model.encode)

Multi-user isolation

alice = Memory(user_id="alice")
bob   = Memory(user_id="bob")

alice.store("I work at Google")
bob.query("where does alice work?")  #> [] — fully isolated

Shared org memories:

alice = Memory(user_id="alice", org_id="acme")
alice.store("Our mission is to democratize AI", scope="shared")

bob = Memory(user_id="bob", org_id="acme")
bob.query("what is our mission?")  #> Returns shared memory

CLI

lore store "I work at Google"
lore query "where do I work?"
lore list
lore stats
lore forget --id <id>
lore serve --port 8420     # REST API
lore mcp                   # MCP server

REST API

pip install loremem-ai[api]
lore serve --port 8420

# Store
curl -X POST localhost:8420/memory \
  -H "Content-Type: application/json" \
  -d '{"user_id":"alice","text":"I prefer dark mode"}'

# Query
curl "localhost:8420/memory?user_id=alice&query=preferences"

Docker

docker build -t loremem -f docker/Dockerfile .
docker run -p 8420:8000 -v lore_data:/data loremem

Contributing

Contributions welcome. See CONTRIBUTING.md.

git clone https://github.com/loreMemory/loreMemory.git && cd loreMemory
pip install -e ".[dev]" && pytest tests/ -v

Security  ·  Changelog  ·  License

MIT — free for personal and commercial use.