SmartMemory

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

[!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.

---

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 conversation"] -->|LLM extraction| B["Facts"] B --> C[("Knowledge Graph RDF / Turtle")] C -->|SPARQL / OWL rules| D["Inference engine"] D -->|new deductions| C D -->|ambiguous?| E["Human-in-the-loop 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.