@aman_asmuei/amem 0.1.0 → 0.1.2

package/README.md

@@ -1,791 +1,263 @@
-<div align="center">
+# amem
 
-# Aman AI Memory
+The memory layer for AI coding tools. Local-first. Developer-specific. Works everywhere.
 
-**Persistent AI memory in markdown files. Multi-user ready.**
-**Works with any AI. Auto-integrates with Claude Code.**
+[![npm version](https://img.shields.io/npm/v/@aman_asmuei/amem.svg)](https://www.npmjs.com/package/@aman_asmuei/amem)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
 
-[![Claude Code](https://img.shields.io/badge/Claude_Code-Ready-6C5CE7?style=for-the-badge&logo=data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHdpZHRoPSIyNCIgaGVpZ2h0PSIyNCIgdmlld0JveD0iMCAwIDI0IDI0IiBmaWxsPSJ3aGl0ZSI+PHBhdGggZD0iTTEyIDJDNi40OCAyIDIgNi40OCAyIDEyczQuNDggMTAgMTAgMTAgMTAtNC40OCAxMC0xMFMxNy41MiAyIDEyIDJ6bTAgMThjLTQuNDEgMC04LTMuNTktOC04czMuNTktOCA4LTggOCAzLjU5IDggOC0zLjU5IDgtOCA4eiIvPjwvc3ZnPg==)](https://claude.ai/claude-code)
-[![Markdown](https://img.shields.io/badge/Storage-Markdown-000000?style=for-the-badge&logo=markdown)](https://en.wikipedia.org/wiki/Markdown)
-[![License](https://img.shields.io/badge/License-Open_Source-2ECC71?style=for-the-badge)](#credits)
+> Your AI forgets everything between conversations. amem fixes that.
 
-<br>
-
-*Your AI remembers you across conversations — your name, preferences, projects, and decisions.*
-*No database. No API keys. No setup complexity. Just markdown.*
-
-</div>
-
----
-
-## What Is This?
-
-Every time you start a new conversation with an AI (ChatGPT, Claude, Gemini), it forgets everything about you. Your name, your projects, your preferences — gone.
-
-**Aman AI Memory fixes this.** It gives your AI a set of files where it stores what it learns about you. Next conversation, it reads those files and picks up right where you left off.
-
-- **It remembers your name** and how you like to work
-- **It tracks your projects** and decisions you've made
-- **It learns your style** over time, adapting to your preferences
-- **It works with any AI** — Claude Code has full automation, others work with copy-paste
-- **Your data stays on your computer** — no cloud, no accounts, just plain text files
-
----
-
-## Quick Start
-
-### Install (one-liner)
+## Install
 
 ```bash
-curl -fsSL https://raw.githubusercontent.com/amanasmuei/aman-ai-memory/main/get.sh | bash
+npx @aman_asmuei/amem
 ```
 
-Downloads everything, initializes a fresh git repo, and launches the guided setup wizard. Just answer a few questions — pick from numbered choices or press Enter for defaults.
+## What it does
 
-> [!TIP]
-> No terminal experience needed. Git is installed automatically as part of setup. Each install gets its own clean git history — no template commits carried over.
+amem is an MCP server that gives any AI assistant persistent memory about:
 
-<details>
-<summary><strong>Install into a specific folder</strong></summary>
+- **Corrections** — "Don't mock the database in integration tests" *(highest priority, always surfaced)*
+- **Decisions** — "Chose Postgres over MongoDB because of ACID requirements"
+- **Patterns** — "User prefers early returns over nested conditionals"
+- **Preferences** — "Uses pnpm, not npm"
+- **Topology** — "Auth module lives in src/auth/, uses JWT"
+- **Facts** — "Project started in January 2025"
 
-<br>
+Memories are ranked by **relevance x recency x confidence x importance**. Corrections always surface first. Old memories decay. Contradictions are detected. Related memories evolve together.
 
-```bash
-# Custom folder name
-curl -fsSL https://raw.githubusercontent.com/amanasmuei/aman-ai-memory/main/get.sh | bash -s -- my-project/ai-memory
-
-# Or clone and run the wizard (init.sh replaces template history with a fresh repo)
-git clone https://github.com/amanasmuei/aman-ai-memory.git
-cd aman-ai-memory && ./init.sh
-```
-
-</details>
-
-<details>
-<summary><strong>Already have the files?</strong> — just run the wizard</summary>
+## Quick start
 
-<br>
+### Claude Code
 
-```bash
-./init.sh
-```
-
-Or run the steps separately:
+Add to `~/.claude/settings.json`:
 
-```bash
-./setup.sh       # Fill in memory.md only
-./install.sh     # Install hooks into host project only
+```json
+{
+  "mcpServers": {
+    "amem": {
+      "command": "npx",
+      "args": ["-y", "@aman_asmuei/amem"]
+    }
+  }
+}
 ```
 
-</details>
+### Cursor
 
----
+Add to `.cursor/mcp.json`:
 
-## Your First Conversation
+```json
+{
+  "mcpServers": {
+    "amem": {
+      "command": "npx",
+      "args": ["-y", "@aman_asmuei/amem"]
+    }
+  }
+}
+```
 
-There are two ways to get started — pick whichever feels more comfortable:
+### Any MCP client
 
-### Option A: Just start talking (recommended for beginners)
+amem speaks standard MCP over stdio. Any client that supports MCP can connect.
 
-1. **Open Claude Code** in your project folder
-2. **Say hello** — the AI detects this is your first time and walks you through setup
-3. **Answer a few questions** — your name, what you work on, what to call the AI
-4. **Done!** The AI remembers you from now on
+## Tools
 
-The AI asks questions conversationally, 2-3 at a time. No forms, no commands — just a friendly chat.
+### `memory_store`
 
-### Option B: Run the setup wizard first
+Store a typed memory with tags and confidence scoring.
 
-```bash
-./init.sh
 ```
-
-The wizard asks the same questions with numbered choices. Good if you prefer filling things in quickly before your first conversation.
-
-### After Setup
-
-1. **Chat normally** — the AI quietly takes notes as you work together
-2. **Say "save"** before ending important sessions — this tells the AI to remember what it learned
-3. **Next time**, the AI greets you by name and remembers everything from before
-
-That's it. No commands to memorize. Just talk naturally and say "save" when it matters.
-
-> [!TIP]
-> **Using ChatGPT, Gemini, or another AI?** At the start of each conversation, paste: *"Read memory.md and session.md, then follow the instructions in CLAUDE.md."* At the end, say: *"Save progress."*
-
----
-
-## Quick Reference
-
-**Things you can say to the AI:**
-
-| Say this | What happens |
-| --- | --- |
-| *(just start talking)* | AI loads your memory and continues where you left off |
-| **"save"** | AI saves what it learned — patterns, decisions, projects |
-| **"write diary entry"** | AI creates a dated log of today's session |
-| **"plan"** | AI creates a work plan with checkboxes to track |
-| *"what did we decide about X?"* | AI searches its memory and diary for past context |
-
-**Scripts you can run in the terminal (optional — the AI handles most of this):**
-
-| Command | What it does |
-| --- | --- |
-| `./recall.sh <word>` | Search all memory files for a keyword |
-| `./archive.sh` | Clean up old entries when memory gets full |
-| `./add-user.sh <name>` | Add another person's profile |
-| `./switch-user.sh` | Switch between profiles |
-| `./setup.sh` | Reconfigure your AI's name and personality |
-
----
-
-## Project Structure
-
-<details>
-<summary>Click to view all files</summary>
-
-<br>
-
-```text
-aman-ai-memory/
-│
-├── memory.md              Your AI's long-term memory (identity, patterns, decisions)
-├── session.md             Current conversation notes (resets each time)
-├── plans.md               Work plans with checkboxes (created when you say "plan")
-├── diary/                 Daily session logs (optional)
-├── archive/               Old entries moved here to keep memory lean
-│
-├── CLAUDE.md              Instructions the AI follows automatically
-├── .claude/
-│   └── settings.json      Automation hooks (runs behind the scenes)
-│
-├── get.sh                 Remote installer (the curl one-liner)
-├── init.sh                Setup wizard (start here)
-├── setup.sh               Configure your AI's identity
-├── install.sh             Install into an existing project
-├── auto-save.sh           Saves your notes when conversation ends
-├── reset-session.sh       Prepares a fresh session on start
-├── validate-memory.sh     Checks memory files aren't corrupted
-├── archive.sh             Moves old entries to archive
-├── recall.sh              Searches memory for past context
-├── add-user.sh            Adds a new user profile
-├── switch-user.sh         Switches between user profiles
-│
-├── profiles/              Per-user data (multi-user mode only)
-│   └── <name>/
-│       ├── memory.md
-│       ├── session.md
-│       └── diary/
-└── archive/               Archived entries (created by archive.sh)
+memory_store({
+  content: "Never use 'any' type — always define proper interfaces",
+  type: "correction",
+  tags: ["typescript", "types"],
+  confidence: 1.0
+})
 ```
 
-</details>
-
----
-
-## How It Works
-
-Here's what happens behind the scenes during each conversation:
-
-### Conversation Lifecycle
-
-```text
-┌──────────────────────────────────────────────────────────────┐
-│                      SESSION START                            │
-│  ┌─────────────┐   ┌────────────────┐   ┌────────────────┐  │
-│  │ Load memory │──▶│ Reset session  │──▶│ Ready to work  │  │
-│  │ + archive   │   │ + inject time  │   │ (time-aware)   │  │
-│  └─────────────┘   │ + archive diary│   └───────┬────────┘  │
-│                     └────────────────┘           │           │
-│                      DURING SESSION              ▼           │
-│  ┌───────────────────────────────────────────────────────┐   │
-│  │  AI updates Working Notes as you make progress        │   │
-│  │  AI can recall past context from diary and archive    │   │
-│  │  You say "save" for intelligent save (optional)       │   │
-│  │  You say "plan" to create a tracked work plan         │   │
-│  └───────────────────────────────────┬───────────────────┘   │
-│                                      │                       │
-│                      SESSION END     ▼                       │
-│  ┌──────────────┐   ┌────────────────────────────────────┐   │
-│  │ Auto-save    │──▶│ Working Notes → Summary            │   │
-│  │ (mechanical) │   │ Ready for next session             │   │
-│  └──────────────┘   └────────────────────────────────────┘   │
-└──────────────────────────────────────────────────────────────┘
-```
+### `memory_recall`
 
-| Step | When | What Happens |
-| --- | --- | --- |
-| **Load** | Conversation starts | AI reads `memory.md` + `session.md` + `archive/memory-archive.md` |
-| **Reset** | Conversation starts | Session resets, injects current time, archives old diary months |
-| **Adapt** | Conversation starts | AI adapts tone to time of day (morning/afternoon/evening/night) |
-| **Work** | During conversation | AI updates Working Notes, can recall from diary and archive |
-| **Plan** | User says "plan" | AI creates or updates `plans.md` with tracked checkboxes |
-| **Save** | User says "save" | AI saves patterns, decisions, projects (max 10), archives old entries |
-| **Auto-save** | Conversation ends | Working Notes copied to summary mechanically |
-| **Validate** | After every edit | Checks structure, size limits (200/500 lines), and append-only rules |
-
----
-
-### Two Types of Save
-
-<table>
-<tr>
-<th width="200"></th>
-<th width="350">Auto-save (on exit)</th>
-<th width="350">Manual save (user says "save")</th>
-</tr>
-<tr>
-<td><strong>What</strong></td>
-<td>Copies Working Notes to End-of-Session Summary</td>
-<td>Updates patterns, decisions, projects, summary</td>
-</tr>
-<tr>
-<td><strong>How</strong></td>
-<td>Bash script — no AI involved</td>
-<td>AI with full conversation context</td>
-</tr>
-<tr>
-<td><strong>Cost</strong></td>
-<td>0 tokens, instant</td>
-<td>Normal AI usage</td>
-</tr>
-<tr>
-<td><strong>When</strong></td>
-<td>Every exit, automatically</td>
-<td>When you explicitly ask</td>
-</tr>
-<tr>
-<td><strong>Best for</strong></td>
-<td>Preserving context between sessions</td>
-<td>Recording long-term patterns and decisions</td>
-</tr>
-</table>
-
----
-
-### What Each File Stores
-
-| File | What Goes Here | Who Updates It | Resets? |
-| --- | --- | --- | --- |
-| `memory.md` | AI identity, user profile, learned patterns, decision log, projects (max 10) | You (setup) + AI (save) | Never — grows over time |
-| `session.md` | Previous recap, time context, goals, working notes, session summary | AI during conversation | Every conversation |
-| `diary/YYYY-MM-DD.md` | Daily session logs | AI when you ask | Never — append-only |
-| `archive/memory-archive.md` | Archived decisions and completed projects | AI (during archive) | Never — append-only |
-| `plans.md` | Active work plans with checkboxes | AI when you say "plan" | When plans complete |
-
----
-
-## Detailed Setup Guide
-
-### All-in-One (Recommended)
+Semantic search across all memories. Returns results ranked by composite score.
 
-```bash
-curl -fsSL https://raw.githubusercontent.com/amanasmuei/aman-ai-memory/main/get.sh | bash
 ```
-
-The installer downloads everything and launches the guided wizard. It handles:
-
-- Single-user or multi-user mode selection
-- Friendly questions with numbered choices (pick 1, 2, 3...)
-- Sensible defaults (press Enter to skip)
-- Auto-detects if you're in a subfolder and offers to install hooks
-- Initializes a fresh git repo (no template history carried over)
-- Shows a summary when done
-
-> [!TIP]
-> **You can skip the wizard entirely.** If you prefer, just open Claude Code and start talking — the AI will walk you through setup conversationally on your first conversation. See [Your First Conversation](#your-first-conversation).
-
-### Adding to an Existing Project
-
-```bash
-# Download into your project
-curl -fsSL https://raw.githubusercontent.com/amanasmuei/aman-ai-memory/main/get.sh | bash -s -- my-project/ai-memory
-
-# Run the wizard
-cd my-project/ai-memory && ./init.sh
+memory_recall({
+  query: "TypeScript best practices",
+  limit: 5
+})
 ```
 
-> [!NOTE]
-> The wizard auto-detects that you're inside another project and offers to install hooks for you.
-
-### Other AI Platforms (ChatGPT, Gemini, etc.)
-
-<details>
-<summary>Click to expand</summary>
-
-<br>
-
-The auto-save and validation hooks are Claude Code specific. For other platforms:
-
-1. Run `./init.sh` to fill in `memory.md` (or edit `memory.md` directly — replace the `[AI_NAME]` and `[YOUR_NAME]` placeholders with your details)
-2. At the **start** of each conversation, paste:
-
-> Read memory.md and session.md, then follow the instructions in CLAUDE.md for how to manage memory during our session.
-
-3. At the **end** of each conversation, say:
-
-> Save progress to memory.md and session.md.
-
-No automation, but the memory files work the same way.
-
-</details>
-
----
-
-## Usage Guide
-
-### Day-to-Day Workflow
-
-| What You Want | What To Do |
-| --- | --- |
-| Start a conversation | Just start — AI loads memory automatically |
-| Save important context | Say **"save"** |
-| Write a diary entry | Say **"write diary entry"** |
-| Create a work plan | Say **"plan"** — AI creates `plans.md` with checkboxes |
-| Search past context | Run **`./recall.sh <keyword>`** or ask the AI |
-| Exit without saving | Just exit — Working Notes are auto-saved |
-| Archive old entries | Run **`./archive.sh`** or say "save" (AI archives automatically) |
-| Add a team member | Run **`./add-user.sh <name>`** |
-| Switch user profile | Run **`./switch-user.sh <name>`** |
-
-### Tips for Best Results
-
-> [!IMPORTANT]
-> Say **"save"** before ending important sessions. Auto-save preserves your working notes, but only manual save captures learned patterns and decisions intelligently.
-
-1. **Be explicit about decisions.** Say *"let's go with approach X because Y"* — the AI will log it in the Decision Log when you save.
-
-2. **Review `memory.md` occasionally.** Check that learned patterns and decisions are accurate. Delete anything wrong.
-
-3. **Keep it under 200 lines.** Run `./archive.sh` when it grows, or just say "save" — the AI archives automatically when approaching the limit.
-
----
-
-### What the AI Remembers
-
-After a few sessions, `memory.md` will contain:
-
-| Section | Example |
-| --- | --- |
-| **Learned Patterns** | *"Prefers concise answers"*, *"Always wants tests before merging"* |
-| **Decision Log** | *"Chose PostgreSQL over MongoDB — relational data needs"* |
-| **Active Projects** | *"API rewrite — in progress — migrating from REST to GraphQL"* |
-
-This context is loaded at the start of every conversation, so the AI picks up where you left off.
-
----
-
-## Validation
-
-Every edit to memory files is automatically checked in the background. You don't need to do anything — if something goes wrong, the AI is told to fix it.
-
-<details>
-<summary>View all validation checks</summary>
-
-<br>
-
-| Check | What It Catches |
-| --- | --- |
-| Required sections | AI accidentally deleted a section heading |
-| Table format | Decision Log or Active Projects lost their table structure |
-| Placeholder check | `[AI_NAME]` still present — setup not complete (AI will guide you through it) |
-| Size guard | `memory.md` over 200 lines or `session.md` over 500 lines |
-| Append-only integrity | Learned Patterns or Decision Log entries were deleted |
-| Session structure | `session.md` missing required sections |
-| Diary format | Wrong filename, missing fields, missing session header |
-
-</details>
-
----
-
-## Diary Format
-
-<details>
-<summary>View diary entry template</summary>
-
-<br>
-
-One file per day (`diary/YYYY-MM-DD.md`), multiple entries appended. Never edit past entries.
-
-```markdown
-## Session — HH:MM
-**Topics**: [comma-separated]
-**Summary**: [1-2 sentences]
-**Decisions**: [any choices made]
-**Learned**: [new user patterns discovered]
----
+Returns:
 ```
+1. [correction] Never use 'any' type — always define proper interfaces
+   Score: 0.892 | Confidence: 100% | Age: 2d ago
 
-Previous months are automatically archived to `diary/archive/YYYY-MM/` at the start of each conversation.
-
-</details>
-
----
-
-## Multi-User
-
-For teams or shared machines where multiple people need their own AI memory.
-
-### Getting Started
-
-**During initial setup** — the wizard asks "Just me" or "Multiple people":
+2. [pattern] User prefers strict TypeScript with no implicit any
+   Score: 0.756 | Confidence: 85% | Age: 5d ago
+```
 
-```text
-  How will this be used?
+### `memory_context`
 
-  1) Just me — single user
-  2) Multiple people — shared project
+Load full context for a topic. Groups by type with corrections first.
 
-  Pick one [1]: 2
-  Your profile name [aman]:
+```
+memory_context({
+  topic: "authentication system",
+  max_tokens: 2000
+})
 ```
 
-Each user gets an isolated profile with their own `memory.md`, `session.md`, and `diary/`.
+Returns:
+```markdown
+## Context for: authentication system
 
-### Adding Users Later
+### Corrections
+- Never store JWT secrets in environment variables (100% confidence)
 
-Already running single-user? No problem — `add-user.sh` migrates your data automatically:
+### Decisions
+- Chose OAuth2 + PKCE for the auth flow (90% confidence)
 
-```bash
-./add-user.sh alice
+### Topology
+- Auth module is in src/auth/, middleware in src/middleware/auth.ts (85% confidence)
 ```
 
-> [!NOTE]
-> The first time you add a user, the script asks for a name for your **existing** profile so your data is preserved. After that, it simply creates a new empty profile.
+### `memory_extract`
 
-### Switching Profiles
+Batch-extract memories from a conversation. The AI calls this proactively.
 
-```bash
-./switch-user.sh            # Interactive — lists all profiles, pick one
-./switch-user.sh alice      # Switch directly
 ```
-
-After switching, all scripts, hooks, and AI instructions work with the new profile — no reconfiguration needed.
-
-### How It Works
-
-Root files (`memory.md`, `session.md`, `diary/`) become **symlinks** to the active profile. This means zero changes to CLAUDE.md, hooks, or AI workflows.
-
-```text
-aman-ai-memory/
-├── memory.md → profiles/aman/memory.md    (symlink)
-├── session.md → profiles/aman/session.md  (symlink)
-├── diary → profiles/aman/diary            (symlink)
-│
-└── profiles/
-    ├── aman/
-    │   ├── memory.md        ← AI reads/writes here when aman is active
-    │   ├── session.md
-    │   ├── diary/
-    │   └── archive/
-    └── alice/
-        ├── memory.md
-        ├── session.md
-        ├── diary/
-        └── archive/
+memory_extract({
+  memories: [
+    { content: "Don't mock the DB in integration tests", type: "correction", confidence: 1.0, tags: ["testing"] },
+    { content: "Chose event sourcing for audit trail", type: "decision", confidence: 0.9, tags: ["architecture"] }
+  ]
+})
 ```
 
-### Multi-User Commands
-
-| Command | What It Does |
-| --- | --- |
-| `./add-user.sh <name>` | Create a new profile (migrates single-user data if needed) |
-| `./switch-user.sh` | List profiles and switch interactively |
-| `./switch-user.sh <name>` | Switch to a specific profile directly |
-| `./setup.sh` | Reconfigure the **active** profile's identity and preferences |
-
----
-
-## Archiving
-
-AI context windows have limits. When `memory.md` exceeds ~200 lines, details in the middle get lost. The archiving system keeps your memory lean while preserving history.
+Automatically deduplicates — if a memory is >85% similar to an existing one, it reinforces the existing memory instead of creating a duplicate.
 
-### What Gets Archived
+### `memory_forget`
 
-| Entry Type | Trigger | Example |
-| --- | --- | --- |
-| **Completed projects** | Status is *done*, *completed*, *shipped*, *cancelled*, or *closed* | `API rewrite — Completed — shipped to prod` |
-| **Old decisions** | Date older than 90 days (configurable) | `2024-11-01 — Chose PostgreSQL over MongoDB` |
+Delete specific memories or search-and-delete with confirmation.
 
-Archived entries move to `archive/memory-archive.md`.
-
-> [!IMPORTANT]
-> **Archived memories are NOT lost.** The AI loads the archive file at the start of every conversation alongside `memory.md`. You don't need to do anything — old decisions and completed projects are still recalled automatically.
-
-### How Recall Works
-
-```text
-Conversation starts
-  │
-  ├─ 1. Read memory.md                  ← active memory (always loaded)
-  ├─ 2. Read session.md                 ← last session recap (always loaded)
-  └─ 3. Read archive/memory-archive.md  ← archived history (loaded if exists)
 ```
-
-| Memory type | Stored in | Loaded automatically? | Purpose |
-| --- | --- | --- | --- |
-| **Active** | `memory.md` | Yes, always | Current identity, patterns, active projects |
-| **Archived** | `archive/memory-archive.md` | Yes, if file exists | Past decisions, completed projects |
-| **Session** | `session.md` | Yes, always | Previous session recap, working notes |
-| **Diary** | `diary/YYYY-MM-DD.md` | On demand | Detailed daily logs (AI checks when asked) |
-
-Archiving keeps `memory.md` lean (under 200 lines) while the AI still has full historical context through the archive file. Think of it like moving old emails to a folder — they're organized separately but still searchable.
-
-### Automatic (during "save")
-
-When you say **"save"**, the AI checks the line count. If `memory.md` is approaching 200 lines, it automatically archives eligible entries before saving new ones.
-
-### Manual
-
-```bash
-./archive.sh                # Interactive — previews what can be archived, asks to confirm
-./archive.sh --days 60      # Archive decisions older than 60 days instead of the default 90
+memory_forget({ id: "abc12345" })
+memory_forget({ query: "old project", confirm: true })
 ```
 
-Example output:
-
-```text
-Memory Archive
-
-  Current size: 187 lines (approaching 200 limit)
-
-  Completed projects: 2
-    → API rewrite
-    → Auth migration
-
-  Decisions older than 90 days: 3
-    → 2024-09-15: Chose PostgreSQL over MongoDB
-    → 2024-10-01: Adopted trunk-based branching
-    → 2024-11-20: Moved CI to GitHub Actions
-
-  Archive these entries? [Y/n]: y
+### `memory_stats`
 
-  ✓ Archived 12 lines
-  ✓ memory.md: 187 → 175 lines
-  ✓ Archive: archive/memory-archive.md
-```
-
-### Accessing Archived Context
+Show memory statistics: total count, breakdown by type, confidence distribution.
 
-The AI can read `archive/memory-archive.md` when historical context is needed. Just ask:
+### `memory_export`
 
-> *"Check the archive — what database did we decide on last year?"*
+Export all memories as formatted markdown, grouped by type.
 
----
+## MCP Prompts
 
-## Advanced Features
+amem includes two prompts that teach AI clients how to use it effectively:
 
-### Time-Aware Behavior
+- **`extraction-guide`** — When and what to extract from conversations
+- **`session-start`** — How to load relevant context at conversation start
 
-The AI adapts its communication style based on the time of day. The current time is automatically injected into `session.md` at the start of each conversation — no configuration needed.
+## MCP Resources
 
-| Time | Tone |
-| --- | --- |
-| **Morning** (6–12) | Fresh, energetic, proactive |
-| **Afternoon** (12–18) | Focused, productive, direct |
-| **Evening** (18–22) | Relaxed, reflective, thorough |
-| **Night** (22–6) | Calm, concise, gentle |
+Proactive context that clients can read automatically:
 
-### Memory Recall
+| Resource | Description |
+|----------|-------------|
+| `amem://corrections` | All active corrections — hard constraints |
+| `amem://decisions` | Architectural decisions and rationale |
+| `amem://profile` | Developer preferences and patterns |
+| `amem://summary` | Quick overview of all stored memories |
 
-Can't remember when you made a decision? The recall system searches across all memory sources:
+## CLI
 
 ```bash
-./recall.sh PostgreSQL       # Search for a keyword
-./recall.sh "API rewrite"    # Search for a phrase
-./recall.sh auth migration   # Multiple keywords (OR)
+amem-cli recall "authentication"    # Search memories
+amem-cli stats                      # Show statistics
+amem-cli list --type correction     # List by type
+amem-cli export --file memories.md  # Export to markdown
+amem-cli forget abc12345            # Delete a memory
 ```
 
-The AI also does this automatically — if you ask about something not in active memory, it searches diary entries and the archive before responding. It will **never fabricate past events** — it searches for evidence first, and says "I'm not sure" if nothing is found.
-
-```text
-Memory Recall — searching for: PostgreSQL
-
-Diary entries:
-
-  2026-03-15
-    L5: **Decisions**: Chose PostgreSQL over MongoDB for relational data
-    L8: Discussed migration plan from SQLite
+## How it works
 
-Archive (memory-archive.md):
-  L12: | 2025-12-01 | Chose PostgreSQL over MongoDB | relational data needs |
-
-Current memory (memory.md):
-  L28: - User prefers PostgreSQL for relational workloads
 ```
-
-### Work Plans
-
-Say **"plan"** to create a tracked work plan:
-
-```markdown
-# Plans
-
-## API Migration — started 2026-03-19
-
-- [x] Design new schema
-- [x] Write migration script
-- [ ] Test with staging data
-- [ ] Deploy to production
-- [ ] Monitor for 48 hours
+┌─────────────────────────────────┐
+│         AI Client               │
+│  Claude Code · Cursor · Any MCP │
+└──────────┬──────────────────────┘
+           │ MCP Protocol (stdio)
+┌──────────▼──────────────────────┐
+│         amem server             │
+│                                 │
+│  ┌───────────┐  ┌────────────┐  │
+│  │  Scoring   │  │  Conflict  │  │
+│  │  Engine    │  │  Detection │  │
+│  └─────┬─────┘  └─────┬──────┘  │
+│        │              │         │
+│  ┌─────▼──────────────▼──────┐  │
+│  │    SQLite + Embeddings    │  │
+│  │    ~/.amem/memory.db      │  │
+│  └───────────────────────────┘  │
+└─────────────────────────────────┘
 ```
 
-Plans persist in `plans.md` across sessions. Progress is updated when you say "save". Completed plans are moved to the archive.
-
-### Smart Project Management (LRU)
-
-Active projects are capped at **10** in `memory.md`. The AI manages this automatically during "save":
-
-- Projects not mentioned in 30+ days are archived
-- Completed projects are always archived
-- Archived projects are still searchable via recall
+### Scoring formula
 
-This prevents `memory.md` from growing unbounded while keeping recent work front and center.
-
-### Diary Auto-Archiving
-
-Diary entries from previous months are automatically moved to `diary/archive/YYYY-MM/` at the start of each conversation. Current month entries stay in `diary/` for quick access.
-
-```text
-diary/
-  2026-03-15.md        ← current month, stays here
-  2026-03-18.md
-  archive/
-    2026-01/           ← previous months, auto-archived
-      2026-01-05.md
-      2026-01-12.md
-    2026-02/
-      2026-02-03.md
+```
+score = relevance x recency x confidence x importance
 ```
 
-Archived diary entries are still searchable via `./recall.sh` and by the AI during recall.
-
-### Session Size Guard
-
-`session.md` is capped at **500 lines**. If Working Notes grow past this, the validation system warns you to save or trim. This prevents session bloat that degrades AI performance.
-
----
-
-## FAQ
-
-<details>
-<summary><strong>Do I need to know how to code?</strong></summary>
-
-<br>
-
-No. You don't even need to run the setup wizard — just start a conversation and the AI will ask you a few friendly questions to get set up. After that, you just talk normally. The only "technical" thing is running the install command once to download the files.
-
-</details>
-
-<details>
-<summary><strong>What if I forget to say "save"?</strong></summary>
-
-<br>
-
-Your working notes are automatically saved when the conversation ends. But only a manual "save" captures learned patterns and decisions intelligently. For casual conversations, auto-save is fine. For important sessions where you made decisions, say "save" before leaving.
-
-</details>
-
-<details>
-<summary><strong>Can I use this with ChatGPT, Gemini, or other AIs?</strong></summary>
-
-<br>
-
-Yes! The automation (auto-save, validation) is Claude Code specific, but the memory files work with any AI. At the start of each conversation, paste:
-
-> *"Read memory.md and session.md, then follow the instructions in CLAUDE.md for how to manage memory during our session."*
-
-At the end, say: *"Save progress to memory.md and session.md."*
-
-</details>
-
-<details>
-<summary><strong>What if memory gets too big?</strong></summary>
-
-<br>
-
-The AI handles this automatically during "save" by archiving old entries. You can also run `./archive.sh` manually. **Archived memories are NOT lost** — they're moved to a separate file that the AI still reads at the start of every conversation.
-
-</details>
-
-<details>
-<summary><strong>Can multiple people use this on the same project?</strong></summary>
-
-<br>
-
-Yes! Run `./add-user.sh alice` to add a new profile. Each person gets their own separate memory, diary, and session. Switch between people with `./switch-user.sh`. See the [Multi-User](#multi-user) section for details.
-
-</details>
-
-<details>
-<summary><strong>Is my data sent anywhere?</strong></summary>
-
-<br>
-
-No. Everything stays in plain text files on your computer. The AI reads these files during your conversation — they're never uploaded to any external service. You own and control your data completely.
-
-</details>
-
-<details>
-<summary><strong>Can I edit the memory files manually?</strong></summary>
-
-<br>
-
-Yes! They're plain text (markdown) files. Open them in any text editor to review, correct, or delete entries. Just keep the section headings (lines starting with `##`) intact.
-
-</details>
-
-<details>
-<summary><strong>What's the difference between memory, session, and diary?</strong></summary>
-
-<br>
-
-Think of it like this:
-
-- **Memory** (`memory.md`) = your AI's brain — who you are, what you prefer, what you're working on. Persists forever.
-- **Session** (`session.md`) = a sticky note for the current conversation. Thrown away and replaced each time.
-- **Diary** (`diary/`) = a journal. One entry per day, never edited. Good for looking back at what happened.
-
-</details>
-
----
-
-## Troubleshooting
+| Factor | How it works |
+|--------|-------------|
+| **Relevance** | Cosine similarity between query and memory embeddings (0-1) |
+| **Recency** | Exponential decay: `0.995^hours_since_last_access` |
+| **Confidence** | How many times confirmed (0-1, corrections from user = 1.0) |
+| **Importance** | Memory type weight: correction(1.0) > decision(0.85) > pattern(0.7) > preference(0.7) > topology(0.5) > fact(0.4) |
 
-| Problem | Solution |
-| --- | --- |
-| AI doesn't remember me | Make sure you're in the right folder. Open `memory.md` — does it have your name? If not, just start a new conversation and the AI will guide you through setup. |
-| "memory.md not found" error | Make sure you're inside the ai-memory folder. If the file is missing, run `./init.sh` to create it. |
-| AI keeps asking my name | Setup wasn't completed. Start a new conversation — the AI will detect this and walk you through it. Or run `./setup.sh` manually. |
-| Memory feels incomplete | Say **"save"** more often. Auto-save only captures working notes, not learned patterns. |
-| "memory.md is over 200 lines" | Run `./archive.sh` to move old entries to the archive. Nothing is lost. |
-| Session feels slow or repetitive | Session might be too long. Say **"save"**, then start a new conversation. |
-| Wrong user profile active | Run `./switch-user.sh` to see who's active and switch if needed. |
-| AI invents things that didn't happen | Say *"check the archive"* or *"search for X"* — the AI is instructed to search, not fabricate. |
+### Conflict detection
 
----
+When storing a new memory, amem checks for conflicts:
+- **>85% similarity** with different content — conflict detected, existing memory updated
+- **>80% similarity** with same intent — existing memory reinforced (confidence +0.1)
+- **No match** — new memory stored
 
-## Known Limitations
+### Memory evolution
 
-| Limitation | Impact | Workaround |
-| --- | --- | --- |
-| AI might not update Working Notes | Auto-save has nothing to copy | Say "save" manually for important sessions |
-| No cross-project memory | Each project has its own memory | Share `memory.md` manually if needed |
-| Keyword search only | Recall uses keyword matching, not semantic search | Use specific keywords with `./recall.sh` |
-| Context window cap | Very large archives may exceed AI context | Keep `memory.md` lean via archiving; archive is loaded but prioritized lower |
+When a new memory is stored, related existing memories (0.6-0.8 similarity) are reinforced — their access timestamps update, keeping them active and relevant.
 
----
+### Local-first
 
-<div align="center">
+- All data stays on your machine at `~/.amem/memory.db`
+- Embeddings generated locally via `all-MiniLM-L6-v2` (~80MB model, runs on CPU)
+- No cloud, no API keys, no data leaving your laptop
+- Works offline after first model download
 
-## Credits
+## Configuration
 
-Inspired by [Project-AI-MemoryCore](https://github.com/Kiyoraka/Project-AI-MemoryCore) by Kiyoraka Ken & Alice
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `AMEM_DIR` | `~/.amem` | Directory for amem data |
+| `AMEM_DB` | `~/.amem/memory.db` | Database file path |
 
-Simplified and enhanced by **Aman**
+## Roadmap
 
----
+- [x] 7 MCP tools (store, recall, context, forget, extract, stats, export)
+- [x] 2 MCP prompts (extraction guide, session start)
+- [x] 4 MCP resources (corrections, decisions, profile, summary)
+- [x] CLI with 5 commands
+- [x] Local embeddings via HuggingFace transformers
+- [x] Memory evolution (related memories reinforce each other)
+- [x] Conflict detection and deduplication
+- [x] Published on npm
+- [ ] Memory verification (check code-related memories against filesystem)
+- [ ] Knowledge graph (entity + relation tables)
+- [ ] Team memory (shared project context via git-synced SQLite)
+- [ ] Proactive mid-conversation context injection
 
-*Built for humans who want their AI to actually remember them.*
+## License
 
-</div>
+MIT

package/package.json

@@ -1,13 +1,15 @@
 {
   "name": "@aman_asmuei/amem",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "The memory layer for AI coding tools. Local-first, developer-specific, works everywhere.",
   "type": "module",
   "bin": {
     "amem": "dist/index.js",
     "amem-cli": "dist/cli.js"
   },
-  "files": ["dist"],
+  "files": [
+    "dist"
+  ],
   "scripts": {
     "build": "tsc",
     "dev": "tsc --watch",
@@ -16,14 +18,22 @@
     "prepare": "npm run build",
     "start": "node dist/index.js"
   },
-  "keywords": ["mcp", "memory", "ai", "developer-tools", "context", "sqlite", "embeddings"],
+  "keywords": [
+    "mcp",
+    "memory",
+    "ai",
+    "developer-tools",
+    "context",
+    "sqlite",
+    "embeddings"
+  ],
   "license": "MIT",
   "author": "Aman Asmuei",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/amanasmuei/aman-ai-memory.git"
+    "url": "git+https://github.com/amanasmuei/amem.git"
   },
-  "homepage": "https://github.com/amanasmuei/aman-ai-memory#readme",
+  "homepage": "https://github.com/amanasmuei/amem#readme",
   "engines": {
     "node": ">=18.0.0"
   },