Project memory.
Sessions start from a clean context window. Memory fixes that — a local database of facts about your project that the agent can query at any time. After a few sessions, Nilux stops asking you to repeat yourself.
How it works
Memory is a set of LLM tools, not a static file. The agent decides when to save and when to search:
recall— search stored memories. The agent calls this at the start of non-trivial tasks to load relevant context.remember— save a fact with a title, content, tags, and memory type (decision, bug_fix, pattern, convention, etc.)forget— remove a memory
The agent learns when to use these from instructions in its system prompt. You can also ask it explicitly: "remember that we use pnpm, not npm" or "what do you know about the auth module?".
bash❯remember that billing tests must run against a real database, not mocks> memory_remember✓ saved · "billing tests: real DB, no mocks" · tags: billing, testing# Later, in a new session:❯write tests for the billing module> memory_recall · found 2 relevant memories└ "billing tests: real DB, no mocks"
Where it lives
One SQLite database on your machine:
plaintext~/.nilux/memory/memory.db # local SQLite database
Memories are indexed for retrieval — when the agent calls recall, it finds relevant entries based on your query. No memory content leaves your machine unless you enable cloud sync.
Memory types
Every memory has a type that helps with organization and search:
decision— architectural or technical decisions with reasoningbug_fix— bugs found and their root causespattern— reusable patterns discovered during workconvention— naming, style, or process conventionsblocker— limitations or known issueslearning— something unexpected learnedcontext— session summaries and ongoing work state
Scoping
Memories are scoped by project_id — derived from the project directory path. When you recall inside a project, only that project's memories are searched by default. Omit the project_id to search across all projects — useful for cross-project patterns.
Beyond the basics
The core tools are remember, recall, and forget. The agent also has access to tools for checking project memory status, linking related memories together, and tracking recurring patterns across sessions.
Enabling and disabling
Memory is toggled via /config inside a session. When disabled, no memory tools are loaded and no extra tokens are spent on memory instructions.
Start with memory OFF for quick one-off tasks. Turn it ON for projects you return to regularly — the investment pays off after 2-3 sessions.
Cloud sync
Optionally sync memories for backup and cross-device access. Use /sync memory to trigger a manual sync, or enable auto-sync in your config. Sync is bidirectional — pull remote changes first, then push local changes.
Without sync configured, all data stays on your machine in the local SQLite file.
Session memory
Separate from the memory database, Nilux also maintains a session_memory.md file per project. This is a plain-text summary generated after each /compact — it captures the conversation state so the next session can pick up where you left off. Stored at ~/.nilux/projects/<slug>/session_memory.md.
Memory contents are sent to the LLM as tool results when the agent calls recall. The local database file itself is never uploaded unless you explicitly configure cloud sync.