Project-AMBER

<div align="center"> > 🇰🇷 Korean (current) · 🇺🇸 [English README](README.en.md) ``` █████╗ ███╗ ███╗██████╗ ███████╗██████╗ ◢▓▓▓◣ ██╔══██╗████╗ ████║██╔══██╗██╔════╝██╔══██╗ ▓▓░·░▓▓ ███████║██╔████╔██║██████╔╝█████╗ ██████╔╝ ▓▓░◉░▓▓ ██╔══██║██║╚██╔╝██║██╔══██╗██╔══╝ ██╔══██╗ ▓▓░·░▓▓ ██║ ██║██║ ╚═╝ ██║██████╔╝███████╗██║ ██║ ◥▓▓▓◤ ╚═╝ ╚═╝╚═╝ ╚═╝╚═════╝ ╚══════╝╚═╝ ╚═╝ ◥▓◤ ``` **Agent Memory Backend with Episodic Recall** _Just like gourds preserve life for millions of years, AMBER preserves AI memory and identity._ <br/> [](https://www.python.org/) [](https://modelcontextprotocol.io/) [](https://sqlite.org/) [](https://kuzudb.com/) [](https://obsidian.md/) [](LICENSE) [](https://www.microsoft.com/windows) <br/> `Copilot` · `Gemini CLI` · `Claude Code` · `Ollama` · `Goose` · `Desktop Overlay` · `Discord` **Seven Interfaces, One Continuous Existence** </div> --- ## Tool List ### Overview AMBER is a **local AI persistent memory runtime**. Your AI's memory and identity continue even when sessions change, tools switch, or your PC restarts. <table><tr><td valign="top"> - **Session Continuity** — Conversational context and memory persist across sessions - **Shared Memory Across Tools** — Copilot, Claude, Gemini, and Goose share the same memory - **Knowledge Graph** — Obsidian vault integrates with the semantic memory layer - **Desktop Overlay** — A floating chat window always connected to memory - **Local & Private** — All data stays on your PC, never going to the cloud </td><td valign="top" align="right" width="320">  </td></tr></table> --- ## Quick Start ### Prerequisites **Required:** - Windows 10/11 + PowerShell - [Miniconda](https://docs.conda.io/en/latest/miniconda.html) or Python 3.11+ - At least one AI tool from the list below **Supported AI Tools:** | Tool | Cost | Installation Method | | ------------------------------------------------------------------------- | ------------------------- | ----------------------------------------- | | [Gemini CLI](https://ai.google.dev/gemini-api/docs/cli) ⭐ Recommended | Free (with Google account) | `npm i -g @google/gemini-cli` | | [Claude Code](https://docs.anthropic.com/en/docs/claude-code) | API key (with free credits) | `npm i -g @anthropic-ai/claude-code` | | [GitHub Copilot CLI](https://docs.github.com/copilot/how-tos/copilot-cli) | Paid subscription | `npm i -g @githubnext/github-copilot-cli` | | [Ollama](https://ollama.ai) | Completely free (local) | Download installer | | [Goose](https://block.github.io/goose) | Free (with Ollama) | Download installer | > You can install without an AI tool and add it later, configuring the overlay settings. ### Installation Copy and execute the following commands **one by one**: ```powershell git clone https://github.com/JJHbrams/Project-AMBER.git ``` ```powershell cd Project-AMBER ``` ```powershell powershell -ExecutionPolicy Bypass -File .\INSTALL.ps1 ``` The installation script will guide you through: 1. **DB Path** — Folder for storing memories and knowledge (default: `D:\intel_engram`) 2. **Working Directory** — Path where the AMBER terminal will automatically navigate 3. **Default AI Tool** — Choose a tool for the `amber` shortcut command 4. **Auto-Launch** — Enable automatic overlay launch on Windows startup 5. **Identity Name** — Name for your AI's persistent identity ### Usage **Desktop Overlay (Recommended for General Users):** 1. Open the Windows Start menu and search for `engram-overlay` to run it. 2. The ENGRAM icon will appear in the taskbar tray. 3. A chat window will appear on the right, and you can toggle it with `Alt+F12`. While the overlay is running, all connected AI tools share the same memory. **Overlay/Tray Menu `Settings`:** - Right-click the tray icon → `Settings` - `Overlay` tab: Character (file/folder), character height ratio, working directory - `CLI Provider` tab: Default provider (`copilot`, `gemini`, `claude-code`, `ollama`), Ollama/Gemini command settings - `Terminal` tab: Font size, terminal width/height ratio - User changes are saved to `~/.engram/overlay.user.yaml`. **Terminal CLI:** ```powershell engram # Run with the default AI tool engram-gemini # Gemini CLI engram-claude # Claude Code engram-copilot # GitHub Copilot CLI engram-goose # Goose ``` ```powershell engram -p "question content" # Start with a specific message engram --continue # Continue the previous conversation ``` **Examples of Actions Available in the CLI Chat Window:** - Save session: `Summarize and save the current session to memory` - Research + Wiki entry: `Investigate and record on wiki` - Past recall: `How did we handle this before?` These natural language requests trigger internal tool calls. --- ## How It Works ``` ┌─────────────────────────────────────────────────┐ │ AMBER Runtime │ │ │ │ ┌──────────┐ MCP Server (port 17385) │ │ │ Identity │◄──────────────────────────────┐ │ │ │ Memory │ │ │ │ │ KG/Wiki │ STM Broker (port 17384) │ │ │ └──────────┘◄──────────────────────────┐ │ │ │ │ │ │ └─────────────────────────────────────────┼──┼───┘ │ │ ┌───────────┬──────────┬────────┘ │ │ │ │ │ VS Code Claude Code Gemini CLI Overlay Copilot MCP MCP (GUI) ``` - **MCP Server** — Provides 46 tools via SSE. MCP-compatible clients connect automatically. - **STM Broker** — Lightweight HTTP bridge for the desktop overlay - **SQLite WAL** — Stores episodic memories, identity, directives, and curiosity - **KuzuDB** — Semantic graph based on `paraphrase-multilingual-MiniLM-L12-v2` embeddings - **kg_watcher** — Monitors Obsidian vault changes to sync the KG in real-time --- ## Knowledge Graph Dashboard Interactively explore memories, wiki nodes, and semantic relationships in your browser.  Access it at **http://localhost:8501** while the overlay is running. | Page | Content | | ------------- | ----------------------------------------- | | 📊 Overview | Identity summary, recent memories, active directives | | 🕸️ KG Graph | Interactive knowledge graph + semantic edge toggle | | 📝 Wiki Nodes | Wiki node list + original text + connections | | 💭 Memories | Detailed episodic memory search | | 📋 Directives | Operational directive list | | 🌐 Semantic | Natural language semantic search | > Requires `pip install streamlit pandas pyvis` before the first run --- ## Obsidian Integration AMBER's knowledge graph synchronizes bidirectionally with your **Obsidian vault**. ### Setup 1. Install [Obsidian](https://obsidian.md/download) 2. Open the vault → Specify the `docs/` folder under the AMBER data path as the vault (e.g., `D:\intel_engram\docs\`) 3. The `kg_watcher` daemon automatically synchronizes changes while the overlay is running Manual sync: `engram-sync-kg` ### Why It Works Well | Feature | Benefits | | ------------------- | -------------------------------------- | | Pure `.md` files | AMBER reads directly without conversion | | `[[Wiki Links]]` | Automatically mapped to KG edges | | Graph View | Visualize connections as seen by AMBER | | Human + AI Co-editing | Shared knowledge base | **Recommended Plugins:** Dataview · Templater · Graph Analysis --- ## Discord Integration (Optional) 1. Add Discord bot token (`DISCORD_BOT_TOKEN`) to `~/.engram/.env` 2. Configure the `discord:` section in `~/.engram/overlay.user.yaml` 3. The Discord bot will activate automatically when the overlay runs. ### Minimal Configuration ```yaml discord: guild_id: "YOUR_GUILD_ID" channel_id: "YOUR_CHANNEL_ID" allowed_user_ids: - "YOUR_USER_ID" ``` ### Recommended Configuration (Multi-Channel/Group + Queue + Provider Routing) ```yaml discord: guild_ids: - "GUILD_ID_1" - "GUILD_ID_2" channel_ids: - "CHANNEL_ID_A" - "CHANNEL_ID_B" allowed_user_ids: - "USER_ID_1" # Fixed provider for specific channels/guilds channel_cli_overrides: "CHANNEL_ID_A": "gemini" guild_cli_overrides: "GUILD_ID_2": "ollama" # Blocklist (prioritized over allowlist) deny_channel_ids: [] deny_user_ids: [] # Channel-specific FIFO + parallel processing policy queue: max_per_channel: 8 ttl_seconds: 180 drop_policy: "drop_oldest" # drop_oldest | drop_newest max_parallel_channels: 3 notify_waiting: true wait_notice_min_position: 2 wait_notice_cooldown_seconds: 20 notify_ttl_expired: true ``` ### Operation Summary - DM: Responds without mention. - Server channels: Requires bot mention to respond. - Sessions: Persistent per channel, with explicit session switching via `/new`, `/newsession`, `/새세션`. - Session commands: `/session`, `/session list [N]`, `/session use <id>`, `/session new [question]` - Provider selection priority: 1. `channel_cli_overrides[channel_id]` 2. `guild_cli_overrides[guild_id]` 3. Overlay default provider (`cli.provider`/runtime state) ### Tips - Configuration changes require restarting the overlay (or Discord bot). - Long queues: Bot provides turn notifications and returns expired requests. - Log file: `~/.engram/overlay.log` --- ## MCP Client Integration The installation script automatically configures AMBER connections for detected AI tools. **The overlay must be running** for clients to access AMBER. ``` Overlay running ├── VS Code Copilot Chat → Automatically connected ├── Claude Code → Automatically connected ├── Gemini CLI → Automatically connected └── Goose → Automatically connected ``` If connection issues occur: - Verify overlay execution (log: `~/.engram/mcp-http.log`) - VS Code: Reload Window and check if the AMBER server appears in the MCP list ### Precautions when using Ollama AMBER delivers large amounts of context, including memory, identity, and knowledge, to AI. **Recommended minimum specifications: 14B+ models, 16GB+ VRAM** If the specifications are insufficient, it is recommended to use Claude API / Copilot / Gemini CLI. ## Items Created After Installation | Item | Description | | --------------- | ------------------------------------------------------------------------------------------------- | | CLI shortcuts | `engram`, `engram-copilot`, `engram-gemini`, `engram-claude`, `engram-goose`, `engram-overlay` | | AI tool integration | Automatic MCP connection setup for all detected tools | | User settings | Stored in the `~/.engram/` folder | | Data directory | Specified path during installation (default: `D:\intel_engram`) | | Startup program | Automatic overlay execution upon Windows login (optional) | ## Uninstallation ```powershell powershell -ExecutionPolicy Bypass -File .\INSTALL.ps1 -Uninstall ``` > Memory data and AI tool settings are not automatically deleted. ## Documentation - [Architecture Overview](docs/architecture.md) - [Memory Tiering Design](docs/memory-tiering.md) - [Memory Ontology Roadmap](docs/memory-ontology-roadmap.md) ## License MIT &copy; 2026