{
  "markdown": "# 🧠 SmartMemory\n\n**Give your LLM structured, verifiable memory** — turn conversations into knowledge graphs your AI can reason over.\n\n<p align=\"center\">\n  <em>An MCP server that teaches AI assistants business rules through natural dialogue.</em>\n</p>\n\n<p align=\"center\">\n  <img src=\"https://img.shields.io/badge/license-MIT-green\" alt=\"License: MIT\">\n  <img src=\"https://img.shields.io/badge/python-3.11%2B-blue\" alt=\"Python 3.11+\">\n  <img src=\"https://img.shields.io/badge/protocol-MCP-purple\" alt=\"Model Context Protocol\">\n  <img src=\"https://img.shields.io/badge/reasoning-neuro--symbolic-8A2BE2\" alt=\"Neuro-symbolic\">\n  <img src=\"https://img.shields.io/badge/status-proof--of--concept-orange\" alt=\"Status: PoC\">\n  <img src=\"https://img.shields.io/badge/PRs-welcome-brightgreen\" alt=\"PRs welcome\">\n</p>\n\n> [!CAUTION]\n> **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.\n\n<!-- TODO: add a short GIF of the dashboard + knowledge graph here. A screenshot is worth a thousand commits on a PoC. -->\n\n---\n\n## Why SmartMemory?\n\nLLMs 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.\n\nSmartMemory adds the missing half: a **symbolic brain**.\n\n- Facts you state are stored in an **auditable knowledge graph** (RDF), each with its provenance.\n- Logic is captured as **explicit, inspectable rules** (SPARQL/OWL) — not hidden in weights.\n- New conclusions are **derived, traceable, and reversible** — and ambiguous ones are sent back to *you* for validation.\n\nThe result is an assistant that doesn't just *sound* right — it can **show its reasoning**.\n\n---\n\n## What it can do\n\nSmartMemory turns your AI assistant into a domain expert that supports:\n\n- **Asynchronous reasoning** — deductions run in the background (`InferenceManager`) without slowing the conversation.\n- **Uncertainty handling** — ambiguous facts trigger a *human-in-the-loop* validation workflow.\n- **Smart NLP extraction** — handles complex sentences, coreferences, and direct Turtle notation.\n- **Provenance & audit** — every stored fact keeps its origin (UUID, source, timestamp).\n- **Dynamic rule engine** — learns and applies new SPARQL rules on the fly.\n\n---\n\n## How it works\n\n```mermaid\nflowchart LR\n    A[\"Natural-language<br/>conversation\"] -->|LLM extraction| B[\"Facts\"]\n    B --> C[(\"Knowledge Graph<br/>RDF / Turtle\")]\n    C -->|SPARQL / OWL rules| D[\"Inference engine\"]\n    D -->|new deductions| C\n    D -->|ambiguous?| E[\"Human-in-the-loop<br/>validation\"]\n    E -->|approve rule / fact| C\n    C -->|provenance + audit| F[\"Verifiable answers\"]\n```\n\nThe 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*.\n\n---\n\n## Two ways to use it\n\n| | 💬 **Conversational Mode** — *the \"Brain\"* | 🏗️ **Supervision Mode** — *the \"Factory\"* |\n|---|---|---|\n| **For** | Individuals using an LLM client (Claude Desktop, etc.) | Teams, developers, heavy users |\n| **Goal** | Let your assistant remember facts and learn logic as you chat | Extract thousands of rules from documents (PDFs) and visualize the graph |\n| **How** | Configure it as an MCP server | Deploy the full dashboard via Docker |\n| **Setup** | [Jump to setup ↓](#mode-1--conversational-setup-mcp) | [Jump to setup ↓](#mode-2--supervision-setup-docker) |\n\n---\n\n## Quick start\n\n| I want to… | Go to |\n|---|---|\n| Get running in 5 minutes | [Quick Start Guide](QUICKSTART.md) |\n| Try the advanced demo | [Demo Procedure](docs/demonstration_procedure.md) |\n| Understand the internals | [Architecture](docs/architecture.md) · [Neuro-symbolic principles](docs/neuro-symbolic.md) |\n| Configure a provider | [Configuration reference](CONFIGURATION.md) |\n| Fix a problem | [Troubleshooting](TROUBLESHOOTING.md) |\n| Browse all docs | [Documentation index](docs/INDEX.md) |\n\n---\n\n## Mode 1 — Conversational Setup (MCP)\n\nGives your LLM long-term memory and logical deduction.\n\n### Option A — Docker (recommended) 🐳\n\nNo Python required. The image is published on GitHub Container Registry.\n\n**Claude Desktop** — edit `~/Library/Application Support/Claude/claude_desktop_config.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"smart-memory\": {\n      \"command\": \"docker\",\n      \"args\": [\"run\", \"--rm\", \"-i\", \"ghcr.io/mauriceisrael/smart-memory:latest\"]\n    }\n  }\n}\n```\n\nThe 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. ✅\n\n### Option B — Local server (from source) 🔒\n\nBest for developers and privacy-conscious users.\n\n```bash\ngit clone https://github.com/MauriceIsrael/SmartMemory\ncd SmartMemory\npython3 -m venv venv\nsource venv/bin/activate\npip install -e .\n```\n\nThen point Claude Desktop at your local install:\n\n```json\n{\n  \"mcpServers\": {\n    \"smartmemory\": {\n      \"command\": \"/absolute/path/to/SmartMemory/venv/bin/python\",\n      \"args\": [\"-m\", \"smart_memory.server\"]\n    }\n  }\n}\n```\n\nRestart Claude and try: *\"I know Bob. He goes to work by car. Can he vote?\"* — see the [demo](#interactive-demo--from-facts-to-rules) below.\n\n---\n\n## Mode 2 — Supervision Setup (Docker)\n\nRuns the **web dashboard** and **API server** — ideal for visualizing the knowledge graph, extracting rules from PDFs, and hosting a shared memory for a team.\n\n```bash\n# Dashboard mode — example with Mistral\ndocker run -p 8080:8080 \\\n  -e LLM_PROVIDER=mistral \\\n  -e LLM_MODEL=mistral-large-latest \\\n  -e LLM_API_KEY=your-api-key \\\n  -v $(pwd)/brain:/app/data \\\n  ghcr.io/mauriceisrael/smart-memory:latest dashboard\n```\n\n```bash\n# Dashboard mode — example with a local model (Ollama)\ndocker run -p 8080:8080 \\\n  -e LLM_PROVIDER=ollama \\\n  -e LLM_MODEL=llama3 \\\n  -e LLM_BASE_URL=http://172.17.0.1:11434 \\\n  -v $(pwd)/brain:/app/data \\\n  ghcr.io/mauriceisrael/smart-memory:latest dashboard\n```\n\n> 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`.\n\n---\n\n## LLM configuration\n\nSmartMemory 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=…`).\n\n| Provider | Example models | Notes |\n|---|---|---|\n| **Mistral** | `mistral-large-latest`, `mistral-small-latest` | European, [La Plateforme](https://mistral.ai/) API |\n| **Ollama** (local, free) | `llama3`, `qwen2.5-coder`, `mistral` | Runs offline |\n| **OpenAI** | `gpt-4`, `gpt-3.5-turbo` | |\n| **Anthropic** | `claude-3-5-sonnet` | |\n| **Google** | `gemini-1.5-pro` | |\n\n→ [Full configuration guide](CONFIGURATION.md)\n\n### Extracting rules from documents\n\n1. **Upload a PDF** (e.g. `Company_Policy.pdf`).\n2. **Pick a provider** — the server needs an API key (or a local Ollama) to read the document.\n3. **Review & approve** — the system proposes rules; you accept them in bulk from the dashboard.\n\n---\n\n## Interactive demo — from facts to rules\n\nWhat happens in **Conversational Mode**:\n\n```text\n> I know Bob\nLLM: ✦ I've recorded the fact: I know Bob.\n\n> He goes to work by car\nLLM: ✦ Noted: Bob goes to work by car.\n\n> Can Bob vote?\nLLM: ✦ I can't conclude yet — but since he drives, he is likely an adult.\n     May I add the rule \"Drivers are adults\"?\n\n> yes\nLLM: ✨ Rule 'drivers_are_adults' added.\n     May I also add \"Adults can vote\"?\n\n> yes\nLLM: ✨ Rule 'adults_can_vote' added.\n     ✦ Therefore, yes — Bob can vote. (derived from 2 rules)\n```\n\nEvery step is stored, attributed, and replayable — that's the point.\n\n---\n\n## Tech stack\n\n- **Backend:** Python 3.11+, RDFLib, FastAPI\n- **Frontend:** SvelteKit, TypeScript, TailwindCSS\n- **Reasoning:** Neuro-symbolic (LLM + SPARQL / OWL)\n- **Protocol:** Model Context Protocol (MCP)\n- **Packaging & deploy:** Docker, GitHub Container Registry, Google Cloud Run\n\n---\n\n## Roadmap\n\n- [ ] Broaden document ingestion (DOCX, HTML, web pages)\n- [ ] Richer graph visualization and rule-conflict detection\n- [ ] First tagged release (`v0.1.0`)\n\nIdeas and contributions welcome — see [CONTRIBUTING.md](CONTRIBUTING.md).\n\n---\n\n## License\n\nMIT — see [LICENSE](LICENSE).\n",
  "bytes": 8526,
  "sha": "8ae62971c751f90aa2db10abdc139bfad3fe02d35e3c6fe53a797c540843bcca",
  "repo_slug": "mauriceisrael/smartmemory",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_mauriceisrael_smartmemory_5eeb2f07/readme"
}