Metadata-Version: 2.4
Name: epistemic-graph-memory
Version: 1.2.1
Summary: A universal, long-term project memory tool utilizing a local SQLite graph structure for AI agents.
Author: Divyansh Ailani
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: mcp>=1.1.2

# Graph-Memory

A universal, long-term project memory tool utilizing a local SQLite graph structure to solve context amnesia for AI coding agents.

**Natively built for Antigravity (AG)**, Graph-Memory provides autonomous AI agents with a highly structured, relational brain. It is exposed universally via the **Model Context Protocol (MCP)**, meaning any framework (Claude Desktop, Cursor, Codex, Aider) can share and update the exact same graph in real-time.

## Overview
When AI agents work on complex software projects over long periods, flat markdown files like `project_memory.md` often fail because they lack structural context and the agent forgets the relationships between different files, tasks, and infrastructure.

**Graph-Memory** solves this by providing a **Trust-Weighted Epistemic Graph** database (SQLite-backed) that your agents interact with to store long-term architecture. It forces agents to provide confidence levels on the facts they log, entirely preventing silent hallucinations.

## File Structure

```
Graph memory/
├── .agents/                    # Database and exports (auto-generated per workspace)
│   ├── graph_memory.sqlite     # The isolated SQLite brain
│   └── graph_memory_vis.html   # The interactive visual graph
├── scripts/
│   ├── db.py                   # Core SQLite bindings, schema, and epistemic logic
│   ├── mcp_server.py           # The Universal Model Context Protocol (MCP) Server
│   └── memory_tool.py          # The CLI tool & HTML Visualizer
├── SKILL.md                    # Antigravity native skill instructions and rules
├── README.md                   # This documentation
├── CHANGELOG.md                # Version history
└── ISSUES.md                   # Known bugs and future roadmap
```

## Features
- **Trust-Weighted Epistemic Graph**: The graph strictly tracks *when* a fact was logged, and *how* it was verified. If an agent just assumes a fact, the graph flags it as stale. It only trusts explicit code reads and executed tests.
- **Idempotent Nodes & Edges**: Agents log Tasks, Decisions, Infrastructure, and Bugs as connected nodes.
- **Strict Modeling Rules**: Rules enforced via instructions ensure no orphaned nodes and strict typing.
- **Obsidian-style Vis.js HTML Export**: Generate beautiful, physics-based, dark-mode graph visualizations in your browser. Stale or hallucinated nodes are visually flagged.
- **Universal State**: The database is stored locally in `.agents/graph_memory.sqlite`, meaning Claude Desktop, Cursor, and Antigravity can all read/write to the exact same brain simultaneously.

## Quickstart

### 1. Installation

You can now install Graph-Memory globally via pip! No more cloning needed.

```bash
pip install epistemic-graph-memory
```

This installs two global commands:
- `graph-memory` (The local CLI tool)
- `graph-memory-mcp` (The MCP server for AI agents)

### 2. Connect to your AI

Graph-Memory exposes the exact 9 standard MCP Tool signatures (`create_entities`, `search_nodes`, `add_observations`, etc.). This makes it a **100% Drop-In Replacement** for the official Anthropic Memory Server.

Add the following to your AI framework's configuration:

**macOS/Linux:**
```json
{
  "mcpServers": {
    "graph-memory": {
      "command": "graph-memory-mcp"
    }
  }
}
```

**Windows:**
```json
{
  "mcpServers": {
    "graph-memory": {
      "command": "graph-memory-mcp"
    }
  }
}
```

---

## Pro-Tip: Enabling "Live" Auto-Updates
In Antigravity (AG), Graph-Memory is deeply integrated, meaning the agent automatically updates the database in the background without you asking.

**To get this same "Live Auto-Update" behavior in Claude Desktop, Cursor, or Codex**, you must paste the following rule into your **Project Instructions**, `.cursorrules`, or `.codexrules` file:

```markdown
# Automated Graph Memory Tracking
You have access to a `graph_memory` MCP server. You MUST proactively and automatically use the `add_node` and `add_relation` tools to track project state without the user explicitly asking you to. 

Whenever you:
1. Complete a significant task or milestone.
2. Make an architectural decision.
3. Discover or setup new infrastructure.

Quietly run the graph tools at the end of your turn to log this information so it isn't forgotten.
```
*Without this rule, Claude/Cursor will treat the graph as a purely manual tool and will only update it when explicitly asked.*

---

## Antigravity Installation (Native)
If you are using Antigravity, you can link this repository directly into your skills folder to use it natively via CLI.

**macOS/Linux:**
```bash
ln -s "/path/to/Graph memory" ~/.gemini/config/skills/graph_memory
```

**Windows (Run Command Prompt as Administrator):**
```cmd
mklink /D "C:\Users\YOUR_USERNAME\.gemini\config\skills\graph_memory" "C:\path\to\Graph memory"
```

### Manual CLI Tools

You can interact with the graph database directly from your terminal using the installed `graph-memory` command! By default, it will look for `.agents/graph_memory.sqlite` in your current working directory.

```bash
# Add an Entity with JSON properties (Observations)
graph-memory add_node "Postgres_DB" "Database" '{"observations": ["Assumed based on backend code."]}'

# Add a Relation
graph-memory add_relation "Server_VM" "HAS_DB" "Postgres_DB"

# Get a Node's Subgraph
graph-memory get_node "Postgres_DB"

# Search using FTS5 Natural Language
graph-memory search "Assumed based on backend"

# Soft-Delete a Node
graph-memory delete_node "Postgres_DB"

# Export Graph to an Interactive HTML file
graph-memory export_html my_graph.html
```

## Advanced Configuration

You can override the default database location by setting the environment variable:
```bash
export GRAPH_MEMORY_DB_PATH="/path/to/my_global_brain.sqlite"
```
