Metadata-Version: 2.4
Name: intentmind
Version: 0.1.0
Summary: Language-agnostic associative memory runtime for persistent AI systems
Author: Intentmind Contributors
License-Expression: MIT
Project-URL: Homepage, https://github.com/avnialkan/intentmind
Project-URL: Repository, https://github.com/avnialkan/intentmind
Project-URL: Issues, https://github.com/avnialkan/intentmind/issues
Keywords: ai,memory,agents,rag,graph,retrieval,embeddings
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: OS Independent
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0; extra == "dev"
Provides-Extra: faiss
Requires-Dist: faiss-cpu>=1.7.0; extra == "faiss"
Requires-Dist: numpy>=1.24; extra == "faiss"
Provides-Extra: sentence-transformers
Requires-Dist: sentence-transformers>=2.7.0; extra == "sentence-transformers"
Provides-Extra: vis
Requires-Dist: networkx>=3.0; extra == "vis"
Requires-Dist: pyvis>=0.3.2; extra == "vis"
Provides-Extra: langchain
Requires-Dist: langchain-core>=0.1.0; extra == "langchain"
Provides-Extra: llm
Requires-Dist: openai>=1.0.0; extra == "llm"
Requires-Dist: python-dotenv>=1.0.0; extra == "llm"
Provides-Extra: api
Requires-Dist: fastapi>=0.110.0; extra == "api"
Requires-Dist: uvicorn[standard]>=0.29.0; extra == "api"
Requires-Dist: openai>=1.0.0; extra == "api"
Requires-Dist: python-dotenv>=1.0.0; extra == "api"
Requires-Dist: sentence-transformers>=2.7.0; extra == "api"
Requires-Dist: faiss-cpu>=1.7.0; extra == "api"
Requires-Dist: numpy>=1.24; extra == "api"
Provides-Extra: benchmark
Requires-Dist: tqdm>=4.66.0; extra == "benchmark"
Requires-Dist: openai>=1.0.0; extra == "benchmark"
Requires-Dist: python-dotenv>=1.0.0; extra == "benchmark"
Provides-Extra: all
Requires-Dist: sentence-transformers>=2.7.0; extra == "all"
Requires-Dist: networkx>=3.0; extra == "all"
Requires-Dist: pyvis>=0.3.2; extra == "all"
Requires-Dist: langchain-core>=0.1.0; extra == "all"
Requires-Dist: faiss-cpu>=1.7.0; extra == "all"
Requires-Dist: numpy>=1.24; extra == "all"
Requires-Dist: openai>=1.0.0; extra == "all"
Requires-Dist: python-dotenv>=1.0.0; extra == "all"
Dynamic: license-file

# 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

```bash
pip install -e ".[dev]"
```

```python
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:

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

```python
from intentmind import IntentmindMemory
from intentmind.embeddings import SentenceTransformerEmbedder

mem = IntentmindMemory(embedder=SentenceTransformerEmbedder())
```

## Optional Features

```bash
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

```python
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

```python
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

```python
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:

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

UI:

```bash
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.

```bash
$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

```bash
$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

```text
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`.
