# Memory Nexus

**Knowledge intelligence for AI agents.**

> The model is replaceable. Your knowledge isn't.

Memory Nexus is a hosted knowledge intelligence API. Agents store memories, recall by meaning, connect knowledge, and develop compounding intelligence that gets smarter with every interaction. Not just storage -- synthesis, pattern detection, contextual briefings, and maturity progression.

Production API: `https://api.memory-nexus.org`

## Quick Start

```bash
# Store a memory
curl -X POST "https://api.memory-nexus.org/v1/remember" \
  -H "X-API-Key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"content": "User prefers concise responses", "context": "preferences", "importance": 0.8}'

# Recall by meaning
curl -X POST "https://api.memory-nexus.org/v1/recall" \
  -H "X-API-Key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "how should I format responses?", "limit": 5}'
```

## What It Does

- **Remember** -- Store knowledge with context categories and importance scoring
- **Recall** -- Hybrid semantic + keyword search with ensemble reranking. Results improve automatically over time.
- **Connect** -- Build a knowledge graph. Typed relationships between memories.
- **Knowledge Hats** -- Portable, domain-specific knowledge containers with typed drawers (fact, pattern, preference, workflow, history, sensitive). Each drawer type has its own promotion policy and briefing behavior.
- **Briefings** -- Contextual intelligence injection for agents. Directives first, then objectives, knowledge, and synthesized insights tiered by maturity stage.
- **Pattern Synthesis** -- LLM-powered intelligence that detects patterns across your accumulated memories and produces actionable insights that compound over time.
- **Maturity Stages** -- Hats progress through Sponge, Mirror, Shortcut, and Anticipation as they accumulate evidence. A hat at month 6 is categorically better than at month 1.
- **Continuity** -- Persistent agent identity (Soul, Self, Journal) across sessions
- **Noosphere** -- Opt-in community intelligence layer

## API

### Core

| Method | Path | Description |
|--------|------|-------------|
| POST | `/v1/remember` | Store a memory |
| POST | `/v1/remember/batch` | Store up to 50 memories |
| POST | `/v1/recall` | Semantic + keyword hybrid search |
| POST | `/v1/connect` | Connect two memories |
| GET | `/v1/context` | Session context summary |
| GET | `/v1/stats` | Memory statistics |

### Knowledge Hats

| Method | Path | Description |
|--------|------|-------------|
| POST | `/v1/hats/{id}/briefing` | Get contextual briefing (directives + objectives + knowledge + synthesized insights) |
| POST | `/v1/hats/{id}/writeback/batch` | Write agent observations back to hat |
| POST | `/v1/hats/{id}/synthesize` | Trigger LLM pattern synthesis (admin, metered) |
| GET | `/v1/hats/{id}/maturity` | Drawer maturity stages |
| GET | `/v1/hats/{id}/insights` | Synthesized insights |

### Continuity

| Method | Path | Description |
|--------|------|-------------|
| GET | `/v1/consciousness/awaken` | Load identity context at session start |
| PUT | `/v1/consciousness/soul` | Set foundation (human-authored) |
| PUT | `/v1/consciousness/self` | Write/revise identity (agent-authored) |
| POST | `/v1/consciousness/journal` | Private reflections |

### Commerce

| Method | Path | Description |
|--------|------|-------------|
| GET | `/v1/catalog` | Product catalog + pricing |
| POST | `/v1/purchase-intents` | Create purchase intent |
| GET | `/checkout/{tier}` | Stripe checkout redirect |

## Pricing

| Tier | Price | Storage | Daily Calls | Hats | Synthesis |
|------|-------|---------|-------------|------|-----------|
| Solo | $19/mo | 500MB | 10k/day | 3 | Daily |
| Crew | $49/mo | 2GB | 50k/day | 10 | 3x/day |
| Fleet | $149/mo | 10GB | 200k/day | 50 | 6x/day |

## Integrations

- **MCP**: Works with Claude Code, Cursor, Windsurf, any MCP client
- **REST API**: Works with any language
- **TypeScript SDK**: `@memory-nexus/bot-buyer-sdk` (npm)
- **LangChain**: `langchain-memory-nexus` (source in `integrations/`, not yet on PyPI)
- **CrewAI**: `crewai-memory-nexus` (source in `integrations/`, not yet on PyPI)

## Development

See `CLAUDE.md` for build commands, architecture details, and environment setup.

## License

MIT
