memory-access

memory-access

An MCP server that gives AI agents persistent, intent-based memory. Text is decomposed into atomic insights, classified into semantic frames, embedded as vectors, and stored in a SQLite knowledge graph with subject indexing.

Quick Start

1. Clone and install

git clone https://github.com/emmahyde/memory-access.git
cd memory-access
uv sync --group dev

Or install from PyPI:

pip install memory-access
# or
uv add memory-access

Requires Python 3.12+.

2. Set environment variables

For OpenAI + Anthropic (default):

export OPENAI_API_KEY=...
export ANTHROPIC_API_KEY=...

For AWS Bedrock:

export EMBEDDING_PROVIDER=bedrock
export LLM_PROVIDER=bedrock
export AWS_PROFILE=your-sso-profile
export AWS_REGION=us-east-1

3. Install the Claude Code plugin

claude plugin install memory-access@emmahyde

4. Set up knowledge base support (optional)

To ingest external documentation as knowledge bases:

export FIRECRAWL_API_KEY=...  # Get from https://www.firecrawl.dev/

5. Verify

uv run pytest          # 174 tests pass
uv run memory-access         # server starts (MCP server mode)
uv run memory-access kb list # knowledge base CLI mode

Configuration

Environment variables

Variable	Required	Description
OPENAI_API_KEY	Yes*	Embedding generation via OpenAI (text-embedding-3-small)
ANTHROPIC_API_KEY	Yes*	Insight normalization via Anthropic (Claude Haiku)
MEMORY_DB_PATH	No	Database path. Default: ~/.claude/memory-access/memory.db
EMBEDDING_PROVIDER	No	openai (default) or bedrock
LLM_PROVIDER	No	anthropic (default) or bedrock
AWS_PROFILE	No	AWS SSO profile name (required for Bedrock)
AWS_REGION	No	AWS region for Bedrock. Default: us-east-1
BEDROCK_EMBEDDING_MODEL	No	Bedrock model ID. Default: amazon.titan-embed-text-v2:0
BEDROCK_LLM_MODEL	No	Bedrock Claude model ID. Default: us.anthropic.claude-haiku-4-5-20251001-v1:0
FIRECRAWL_API_KEY	No	Web crawling for knowledge bases. Get from https://www.firecrawl.dev/
CRAWL_SERVICE	No	Crawl provider. Default: firecrawl
MIN_CONFIDENCE_THRESHOLD	No	Minimum confidence to store ingested chunks. Default: 0.5

* Not required when using bedrock provider.

Claude Code

Add to your MCP settings (see mcp-config-example.json):

{
  "mcpServers": {
    "memory-access": {
      "command": "python3",
      "args": ["-m", "memory_access.server"],
      "env": {
        "MEMORY_DB_PATH": "~/.claude/memory-access/memory.db",
        "OPENAI_API_KEY": "${OPENAI_API_KEY}"
      },
      "cwd": "/path/to/memory-access/src"
    }
  }
}

AWS Bedrock

To use AWS Bedrock instead of OpenAI/Anthropic APIs:

{
  "mcpServers": {
    "memory-access": {
      "command": "python3",
      "args": ["-m", "memory_access.server"],
      "env": {
        "MEMORY_DB_PATH": "~/.claude/memory-access/memory.db",
        "EMBEDDING_PROVIDER": "bedrock",
        "LLM_PROVIDER": "bedrock",
        "AWS_PROFILE": "your-sso-profile",
        "AWS_REGION": "us-east-1"
      },
      "cwd": "/path/to/memory-access/src"
    }
  }
}

MCP Tools (21 tools)

Storage

• store_insight — Store text with optional domain and git context (repo, pr, author, project, task). Text is decomposed into atomic insights, classified, embedded, and indexed.
• update_insight — Update an insight's confidence score.
• forget — Delete an insight.

Search

• search_insights — Semantic similarity search by query text. Returns ranked results.
• list_insights — List insights filtered by domain or frame.
• search_by_subject — Find insights by subject name and kind.
• related_insights — Find insights connected through shared subjects (graph traversal).

Knowledge graph

• add_subject_relation — Create a typed edge between two subjects (e.g., problem --solved_by--> resolution).
• get_subject_relations — Query outgoing relations from a subject.

Knowledge Bases

• add_knowledge_base — Create a new knowledge base by crawling or scraping a URL. Supports both full site crawling and single-page scraping with automatic ingestion and semantic indexing.
• search_knowledge_base — Search external documentation by semantic similarity. Optionally filter by KB name.
• list_knowledge_bases — List all knowledge bases with descriptions and chunk counts.

Task orchestration