intentmind 0.1.0

Language-agnostic associative memory runtime for persistent AI systems

Intentmind

Intentmind is a lightweight associative memory runtime for AI assistants and agent systems. It stores memories as chunks, extracts intent nodes, connects co-occurring intents in a graph, and retrieves context through a mix of direct semantic match and graph traversal.

The goal is to surface relevant context that a plain top-k vector search can miss when the user mentions a related concept instead of the exact old fact.

What It Is

• A Python memory layer for LLM apps, assistants, copilots, and experiments.
• A graph-backed recall runtime with explainable paths such as car -> insurance.
• A small library API: add, query, save, load, tick, graph_summary, and visualize.
• Optional integrations for FAISS, SentenceTransformers, LangChain, and a demo FastAPI/React chat UI.

Intentmind is not a full agent framework, vector database, hosted service, or chatbot by itself.

Quick Start

pip install -e ".[dev]"

from intentmind import IntentmindMemory

mem = IntentmindMemory(is_test=True)

mem.add("I need car insurance but I have no money.")
mem.add("I bought a new car and will drive to London.")

result = mem.query("I have a car and I am going to London.")

for item in result["memories"]["items"]:
    print(item["layer"], item["intent"], item["path"], item["text"])

For production embeddings:

pip install -e ".[sentence-transformers]"

from intentmind import IntentmindMemory
from intentmind.embeddings import SentenceTransformerEmbedder

mem = IntentmindMemory(embedder=SentenceTransformerEmbedder())

Optional Features

pip install -e ".[faiss]"       # FAISS-backed intent index
pip install -e ".[langchain]"   # LangChain retriever adapter
pip install -e ".[vis]"         # graph visualization
pip install -e ".[llm]"         # OpenAI-backed intent extraction examples
pip install -e ".[api]"         # FastAPI demo backend dependencies

If you use OpenAI-backed examples or the demo API, create a local .env from .env.example and set OPENAI_API_KEY.

Core API

chunk_id = mem.add("The car insurance expires next week.", source="user")
result = mem.query("I am planning a road trip.")

print(result["prompt"])
print(result["memories"]["items"])
print(result["trace"])
print(result["cognitive_field"])

Each accepted memory item includes the chunk text, score, layer, triggering intent, path, reason, and edge metadata when the item was reached through the graph.

How Recall Works

1. add() embeds the memory chunk and extracts candidate intents.
2. Intents are reused or created, then co-occurrence edges are reinforced.
3. query() extracts query intents, activates matching graph nodes, and runs a query-time cognitive field step.
4. Recall selects direct memories, one-hop associated memories, and optional weak echo memories.
5. PromptBuilder assembles an LLM-ready prompt with relevant memories and traceable context.

Persistence

mem.save("memory_snapshot.json")
restored = IntentmindMemory.load("memory_snapshot.json", is_test=True)

Generated memory snapshots are ignored by default so local experiments do not leak into the repository.

LangChain Adapter

from intentmind import IntentmindMemory
from intentmind.integrations.langchain import IntentmindRetriever

memory = IntentmindMemory(is_test=True)
retriever = IntentmindRetriever(memory=memory)
docs = retriever.invoke("How does the energy model work?")

Demo API And UI

Backend:

pip install -e ".[api]"
$env:PYTHONPATH="src"; python api.py

UI:

cd ui
npm install
npm run dev

The UI expects POST /api/chat to be reachable from the same origin or through a local proxy.

Benchmarks

Benchmark fixtures live under tests/fixtures. They are useful for regression testing and local comparison against a classic vector-search baseline, but they should not be treated as independent research claims.

$env:PYTHONPATH="src"; python examples/run_benchmark.py
$env:PYTHONPATH="src"; python examples/run_real_world_benchmark.py

Generated benchmark outputs are ignored by Git.

Development

$env:PYTHONPATH="src"; python -m pytest -q
cd ui
npm install
npm run lint
npm run build

Current local verification: 26 passed; UI lint and production build pass.

Repository Layout

src/intentmind/          Python package
tests/                   Unit and regression tests
tests/fixtures/          Deterministic benchmark fixtures
examples/                Usage demos and benchmark runners
ui/                      Optional React/Vite demo
api.py                   Optional FastAPI demo backend

License

MIT. See LICENSE.