SmartMemory

🧠 SmartMemory

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

<p align="center"> <em>An MCP server that teaches AI assistants business rules through natural dialogue.</em> </p>

<p align="center"> <img src="https://img.shields.io/badge/license-MIT-green" alt="License: MIT"> <img src="https://img.shields.io/badge/python-3.11%2B-blue" alt="Python 3.11+"> <img src="https://img.shields.io/badge/protocol-MCP-purple" alt="Model Context Protocol"> <img src="https://img.shields.io/badge/reasoning-neuro--symbolic-8A2BE2" alt="Neuro-symbolic"> <img src="https://img.shields.io/badge/status-proof--of--concept-orange" alt="Status: PoC"> <img src="https://img.shields.io/badge/PRs-welcome-brightgreen" alt="PRs welcome"> </p>

[!CAUTION] Proof of Concept. SmartMemory is an experimental implementation of a neuro-symbolic architecture, built to explore how LLMs can interact with knowledge graphs to learn and apply rules. It is not intended for production use — treat it as a research and learning playground.

<!-- TODO: add a short GIF of the dashboard + knowledge graph here. A screenshot is worth a thousand commits on a PoC. -->

---

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

| | 💬 Conversational Mode — the "Brain" | 🏗️ Supervision Mode — the "Factory" | |---|---|---| | For | Individuals using an LLM client (Claude Desktop, etc.) | Teams, developers, heavy users | | Goal | Let your assistant remember facts and learn logic as you chat | Extract thousands of rules from documents (PDFs) and visualize the graph | | How | Configure it as an MCP server | Deploy the full dashboard via Docker | | Setup | Jump to setup ↓ | Jump to setup ↓ |

---

Quick start

| I want to… | Go to | |---|---| | Get running in 5 minutes | Quick Start Guide | | Try the advanced demo | Demo Procedure | | Understand the internals | Architecture · Neuro-symbolic principles | | Configure a provider | Configuration reference | | Fix a problem | Troubleshooting | | Browse all docs | Documentation index |

---

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=…).

| Provider | Example models | Notes | |---|---|---| | Mistral | mistral-large-latest, mistral-small-latest | European, La Plateforme API | | Ollama (local, free) | llama3, qwen2.5-coder, mistral | Runs offline | | OpenAI | gpt-4, gpt-3.5-turbo | | | Anthropic | claude-3-5-sonnet | | | Google | gemini-1.5-pro | |

→ 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.