Fully Self-evolving AI Companion

FSAR

It belongs to you,not to a vendor.

FSAR is a local-first AI companion. Conversations, memories, decisions and tools all run on your own machine, in a SQLite database under~/.fsar/. Nothing is uploaded to any FSAR server.

Get started Read the docs

Python 3.11+MIT LicenseWindows · Linux · macOSData 100% local

~/.fsar/ · this machine only

character card · user card

memory.db · SQLite

reflection · experience · strategy

It remembersevery word you said to it,and every strategy it learned along the way.When it wakes up next time,none of it is lost.

4design pillars: faithful · safe · adaptive · reflective

3reflection modes: per-task / on-failure / idle-batch

18module pages, file by file

Design contract

The name is the contract.

FSAR is four letters and four constraints that have to hold at the same time. Remove one, and the rest is no longer the same thing.

01 / F

Faithful

忠实

FSAR is the character you configured — name, personality, scenario, emotion state — talking to the user you described. It does not drift into “generic assistant”.

02 / S

Safe

安全

Every tool call passes through layered checks: a hardline guard blocks destructive commands first, a risk engine classifies each tool, a workspace gate contains file access, and a subprocess env scrubber strips keys and tokens before skills run.

03 / A

Adaptive

自适应

Every tool call is logged. A strategy injector synthesises a ## Learned Strategies block from the decision log and user model. An experience store makes one session’s MCP install the next session’s recall.

04 / R

Reflective

反思

Three reflection modes re-read conversations and update the user model: explicit preferences, inferred profile, recurring behavioral patterns. The next session opens with that context already in the prompt.

What it can do

More than chat.

Tools, memory, rooms, sandbox, social bridges — they share the same safety gates and the same ~/.fsar/.

Run commands

PowerShell on Windows, bash elsewhere. Destructive commands are stopped by the hardline guard before any other check runs.

Scoped file work

Read, edit and search inside a scoped workspace. Going out of bounds triggers a sandbox-escape confirmation, not a silent pass.

Web search

Search and fetch the web through the free Exa MCP server — no API key required.

Images and PDFs

Analyse images and PDFs locally. The content does not enter a third-party queue.

Computer Use

Screenshot, click, type and press keys. Gated separately from ordinary conversation.

Rooms of characters

Several characters share one room and elect who speaks next; @-naming one hands them the floor.

Rooms as projects

A plan board, one turn per member in that member’s own copy of the repo, patches you land or refuse by hand, snapshots you publish.

Social bridges

Talk through Telegram, Feishu or WeChat and keep the same conversation going when you are away from the desk.

Headless turns

fsar run for a single turn; fsar room say / read against a room’s API.

Under the hood

One message,
end to end.

From the browser to a character speaking: six explicit gates. If any one refuses, nothing after it happens.

01Ingress

The frontend sends JSON over /ws. ws_server._dispatch tries each handler in turn; chat.send lands in handlers/chat.py, which spawns ChatEngine.handle_send.

02Prepare

Bind the session to a workspace, resolve the character card, emit chat.thinking. Route by content: slash command, multi-model ensemble, companion mode, or the agent loop.

03Assemble the prompt

Take the agent tier and build the system prompt from AGENT_SYSTEM_PROMPT + character/user cards + ## Learned Strategies + ## Experiences, then load short-term memory and trim it to the context window.

04The agent loop

Up to max_tool_turns iterations: compact context when needed, call the model (server-side prompt caching where supported), execute tool calls when present. Higher tiers add adversarial checks and micro-reflection.

05The gates

MCP gate → sandbox gate WorkspaceGate → risk gate RiskEngine → execute → post-execution review and redaction. Sequential, and the first refusal stops the chain.

06Wrap up

Feed tool results back until the model answers without one; stream the answer (optionally TTS), run task reflection by tier, advance idle reflection, lazily name the session.

Where your data lives

Delete one folder.
That is a full reset.

Everything about you lives in ~/.fsar/: configuration, conversations, decision logs, the user model, experiences, semantic embeddings, caches and audit logs.

No account, no cloud sync, no “uploaded to improve the service”. Copy the folder and the whole of FSAR goes with it.

~/.fsar/

~/.fsar/
├── config/              yaml configuration
└── data/
    ├── memory.db         chats · decisions · profile · experience
    ├── chroma/            semantic embeddings
    ├── llm_cache.db       provider prompt-cache accounting
    ├── tts_cache.db       TTS audio cache
    ├── scheduler.db       scheduled jobs
    └── logs/              rolling logs + audit.log

Quick start

Three commands,
on your own machine.

You need Python 3.11+ and Node.js 18+. The first launch installs frontend dependencies and builds the UI; later launches only do an incremental build.

# clone and install $ git clone https://github.com/sildo466/FSAR.git $ cd FSAR $ python -m venv .venv $ .venv\Scripts\activate $ pip install -r requirements.txt # launch $ start.bat

The browser opens to http://127.0.0.1:8765. If it does not, navigate there manually.

# clone and install $ git clone https://github.com/sildo466/FSAR.git $ cd FSAR $ python3 -m venv .venv $ source .venv/bin/activate $ pip install -r requirements.txt # launch $ ./start.sh

On macOS, Computer Use needs Accessibility access for your terminal app and Python in System Settings → Privacy & Security.

# inside the cloned repository $ pip install -e . $ fsar

A full-screen Textual TUI: same ~/.fsar/ data, same tools, same safety gates, no browser. Start in a mode directly with fsar character or fsar companion.

Documentation

As deep as you need.

From a one-page overview, to every key in fsar.yaml, to the responsibilities and key files of 18 source modules. Available in Chinese and English.

02 PAGES

FSAR

The name is the contract.

Faithful

Safe

Adaptive

Reflective

More than chat.

Run commands

Scoped file work

Web search

Images and PDFs

Computer Use

Rooms of characters

Rooms as projects

Social bridges

Headless turns

One message,
end to end.

01Ingress

02Prepare

03Assemble the prompt

04The agent loop

05The gates

06Wrap up

Delete one folder.
That is a full reset.

Three commands,
on your own machine.

As deep as you need.

Getting started

Configuration

Development

Module reference

FSAR

The name is the contract.

Faithful

Safe

Adaptive

Reflective

More than chat.

Run commands

Scoped file work

Web search

Images and PDFs

Computer Use

Rooms of characters

Rooms as projects

Social bridges

Headless turns

One message,end to end.

01Ingress

02Prepare

03Assemble the prompt

04The agent loop

05The gates

06Wrap up

Delete one folder.That is a full reset.

Three commands,on your own machine.

As deep as you need.

Getting started

Configuration

Development

Module reference

One message,
end to end.

Delete one folder.
That is a full reset.

Three commands,
on your own machine.