🧠 SmartMemory

Give your LLM structured, verifiable memory — turn conversations into knowledge graphs your AI can reason over.

An MCP server that teaches AI assistants business rules through natural dialogue.

Why SmartMemory?

LLMs are brilliant talkers with no real memory. Across a conversation they forget, they can't explain why they concluded something, and they happily state things that were never verified.

SmartMemory adds the missing half: a symbolic brain.

• Facts you state are stored in an auditable knowledge graph (RDF), each with its provenance.
• Logic is captured as explicit, inspectable rules (SPARQL/OWL) — not hidden in weights.
• New conclusions are derived, traceable, and reversible — and ambiguous ones are sent back to you for validation.

The result is an assistant that doesn't just sound right — it can show its reasoning.

What it can do

SmartMemory turns your AI assistant into a domain expert that supports:

• Asynchronous reasoning — deductions run in the background (InferenceManager) without slowing the conversation.
• Uncertainty handling — ambiguous facts trigger a human-in-the-loop validation workflow.
• Smart NLP extraction — handles complex sentences, coreferences, and direct Turtle notation.
• Provenance & audit — every stored fact keeps its origin (UUID, source, timestamp).
• Dynamic rule engine — learns and applies new SPARQL rules on the fly.

How it works

flowchart LR
    A["Natural-language<br/>conversation"] -->|LLM extraction| B["Facts"]
    B --> C[("Knowledge Graph<br/>RDF / Turtle")]
    C -->|SPARQL / OWL rules| D["Inference engine"]
    D -->|new deductions| C
    D -->|ambiguous?| E["Human-in-the-loop<br/>validation"]
    E -->|approve rule / fact| C
    C -->|provenance + audit| F["Verifiable answers"]

The LLM is the language cortex (understanding and extraction); the knowledge graph and rule engine are the symbolic memory (storage, logic, proof). Neither alone is enough — together they are neuro-symbolic.

Two ways to use it

Quick start

Mode 1 — Conversational Setup (MCP)

Gives your LLM long-term memory and logical deduction.

Option A — Docker (recommended) 🐳

No Python required. The image is published on GitHub Container Registry.

Claude Desktop — edit ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "smart-memory": {
      "command": "docker",
      "args": ["run", "--rm", "-i", "ghcr.io/mauriceisrael/smart-memory:latest"]
    }
  }
}

The same block works for any MCP client (e.g. Cline) — just point it at your client's mcp_settings.json. Restart the client and you're done. ✅

Option B — Local server (from source) 🔒

Best for developers and privacy-conscious users.

git clone https://github.com/MauriceIsrael/SmartMemory
cd SmartMemory
python3 -m venv venv
source venv/bin/activate
pip install -e .

Then point Claude Desktop at your local install:

{
  "mcpServers": {
    "smartmemory": {
      "command": "/absolute/path/to/SmartMemory/venv/bin/python",
      "args": ["-m", "smart_memory.server"]
    }
  }
}

Restart Claude and try: "I know Bob. He goes to work by car. Can he vote?" — see the demo below.

Mode 2 — Supervision Setup (Docker)

Runs the web dashboard and API server — ideal for visualizing the knowledge graph, extracting rules from PDFs, and hosting a shared memory for a team.

# Dashboard mode — example with Mistral
docker run -p 8080:8080 \
  -e LLM_PROVIDER=mistral \
  -e LLM_MODEL=mistral-large-latest \
  -e LLM_API_KEY=your-api-key \
  -v $(pwd)/brain:/app/data \
  ghcr.io/mauriceisrael/smart-memory:latest dashboard

# Dashboard mode — example with a local model (Ollama)
docker run -p 8080:8080 \
  -e LLM_PROVIDER=ollama \
  -e LLM_MODEL=llama3 \
  -e LLM_BASE_URL=http://172.17.0.1:11434 \
  -v $(pwd)/brain:/app/data \
  ghcr.io/mauriceisrael/smart-memory:latest dashboard

Add dashboard to start the web server; without it the container starts in MCP mode. The -v volume persists your knowledge graph and rules. Open the dashboard at http://localhost:8080.

LLM configuration

SmartMemory uses an LLM to extract facts and rules from natural language and documents. Configure it via the dashboard Admin page or via environment variables (-e LLM_PROVIDER=…).

→ Full configuration guide

Extracting rules from documents

1. Upload a PDF (e.g. Company_Policy.pdf).
2. Pick a provider — the server needs an API key (or a local Ollama) to read the document.
3. Review & approve — the system proposes rules; you accept them in bulk from the dashboard.

Interactive demo — from facts to rules

What happens in Conversational Mode:

> I know Bob
LLM: ✦ I've recorded the fact: I know Bob.

> He goes to work by car
LLM: ✦ Noted: Bob goes to work by car.

> Can Bob vote?
LLM: ✦ I can't conclude yet — but since he drives, he is likely an adult.
     May I add the rule "Drivers are adults"?

> yes
LLM: ✨ Rule 'drivers_are_adults' added.
     May I also add "Adults can vote"?

> yes
LLM: ✨ Rule 'adults_can_vote' added.
     ✦ Therefore, yes — Bob can vote. (derived from 2 rules)

Every step is stored, attributed, and replayable — that's the point.

Tech stack

• Backend: Python 3.11+, RDFLib, FastAPI
• Frontend: SvelteKit, TypeScript, TailwindCSS
• Reasoning: Neuro-symbolic (LLM + SPARQL / OWL)
• Protocol: Model Context Protocol (MCP)
• Packaging & deploy: Docker, GitHub Container Registry, Google Cloud Run

Roadmap

• Broaden document ingestion (DOCX, HTML, web pages)
• Richer graph visualization and rule-conflict detection
• First tagged release (v0.1.0)

Ideas and contributions welcome — see CONTRIBUTING.md.

License

MIT — see LICENSE.